# e2e_rod

**Repository Path**: z1gotool/e2e_rod

## Basic Information

- **Project Name**: e2e_rod
- **Description**: 把个go-rod用于e2e的助手
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gitee.com/z1gotool/e2e_rod

## 项目简介

e2e_rod 是一个基于 [go-rod](https://github.com/go-rod/rod) 的 E2E 浏览器自动化测试库，提供简洁易用的浏览器封装、元素交互、CDP 监听和截图 API，专为 Go 语言生态中的端到端测试场景设计。

## 安装

```bash
go get gitee.com/z1gotool/e2e_rod
```

确保 Go 版本 ≥ 1.24.1，模块会自动引入 `github.com/go-rod/rod` 及其依赖。

## 快速开始（30 秒示例）

```go
package main

import (
	"fmt"
	"time"

	"gitee.com/z1gotool/e2e_rod/rodhelper"
)

func main() {
	browser, err := rodhelper.NewBrowser(rodhelper.WithTimeout(30 * time.Second))
	if err != nil {
		panic(err)
	}
	defer rodhelper.Cleanup(browser)

	page, err := rodhelper.NewPage(browser, "https://example.com")
	if err != nil {
		panic(err)
	}
	defer rodhelper.ClosePage(page)

	title, _ := rodhelper.GetPageTitle(page)
	fmt.Println("页面标题:", title)

	if err := rodhelper.FullPageScreenshot(page, "example.png"); err != nil {
		panic(err)
	}
	fmt.Println("截图已保存: example.png")
}
```

## 架构三层

```
e2e_rod/
├── web_app_example/      # 测试 Web 服务器（内嵌 24 个 HTML 页面，含表单、弹窗、拖放、无限滚动等场景）
├── rodhelper/            # 浏览器自动化封装层（配置、生命周期、元素交互、CDP 监听、截图等核心 API）
└── e2etest/
    └── web_app_example/  # 27 个 E2E 测试用例（同时也是完整的使用示例）
```

| 层 | 目录 | 职责 |
|---|---|---|
| **测试服务器** | `web_app_example/` | Go HTTP 服务器，通过 `//go:embed` 内嵌 24 个静态 HTML 页面，覆盖表单、弹窗、拖放、无限滚动、分页、动画、手风琴等前端常见交互模式 |
| **封装层** | `rodhelper/` | 基于 go-rod 的浏览器封装，统一管理浏览器生命周期、页面导航、元素定位与交互、等待、截图、Console/Network CDP 监听等功能 |
| **E2E 测试** | `e2etest/web_app_example/` | 27 个测试文件（覆盖 24 种交互类型），同时作为 rodhelper API 的完整参考实现 |

## 配置说明

### 配置优先级

```
代码选项（With* 函数） > 环境变量（RODHELPER_*） > rodhelper.yaml > 内置默认值
```

### 环境变量

| 环境变量 | 对应配置 | 默认值 |
|---|---|---|
| `RODHELPER_HEADLESS` | `headless` | `true` |
| `RODHELPER_TIMEOUT` | `timeout` | `10s` |
| `RODHELPER_CONSOLE_MONITOR` | `console_monitor` | `true` |
| `RODHELPER_NETWORK_MONITOR` | `network_monitor` | `true` |
| `RODHELPER_VIEWPORT_WIDTH` | `viewport.width` | `1280` |
| `RODHELPER_VIEWPORT_HEIGHT` | `viewport.height` | `720` |
| `RODHELPER_SCREENSHOT_DIR` | `screenshot_dir` | `screenshots` |
| `RODHELPER_BROWSER_PATH` | `browser.path` | （自动检测） |
| `RODHELPER_BROWSER_USER_DATA_DIR` | `browser.user_data_dir` | （临时目录） |
| `RODHELPER_PROXY_HTTP` | `proxy.http` | `""` |
| `RODHELPER_PROXY_HTTPS` | `proxy.https` | `""` |

### rodhelper.yaml 示例

```yaml
headless: true
timeout: 10s
console_monitor: true
network_monitor: true

viewport:
  width: 1280
  height: 720

screenshot_dir: screenshots

browser:
  path: ""                       # 空字符串表示自动检测
  flags: []
  user_data_dir: ""              # 空字符串表示自动在临时目录创建

proxy:
  enabled: false
  http: ""
  https: ""
```

## rodhelper API 概览

### 浏览器生命周期
- `NewBrowser(opts ...Option) (*rod.Browser, error)` — 创建并启动浏览器实例
- `Cleanup(browser *rod.Browser)` — 关闭浏览器并清理临时用户数据目录
- `IsAlive(browser *rod.Browser) bool` — 检查浏览器实例是否存活

### 页面管理
- `NewPage(browser *rod.Browser, url string, opts ...Option) (*rod.Page, error)` — 创建新页面并导航到 URL，自动注册 CDP 监听器
- `GetPageTitle(page *rod.Page) (string, error)` — 获取页面标题
- `SetViewport(page *rod.Page, width, height int) error` — 设置浏览器视口大小
- `SetDefaultViewport(page *rod.Page) error` — 使用配置中的默认视口大小
- `ClosePage(page *rod.Page) error` — 关闭页面并清理 CDP 监听器

### 元素交互
- `FindElement(page *rod.Page, selector string) (*rod.Element, error)` — 通过 CSS 选择器查找元素
- `Click(element *rod.Element) error` — 点击元素
- `FillInput(element *rod.Element, text string) error` — 在输入框中填入文本（自动触发 input/change 事件）
- `SetCheckbox(element *rod.Element, checked bool) error` — 设置复选框选中状态
- `SelectRadio(element *rod.Element) error` — 选中单选框
- `UploadFile(element *rod.Element, paths ...string) error` — 上传文件到 `<input type="file">`
- `DragAndDrop(source, target *rod.Element) error` — 模拟 HTML5 拖放操作

### 滚动
- `ScrollToElement(element *rod.Element) error` — 将指定元素滚动到视口内
- `ScrollBy(page *rod.Page, deltaX, deltaY int) error` — 按像素偏移量滚动页面

### 等待
- `WaitVisible(page *rod.Page, selector string, timeout time.Duration) error` — 等待元素可见
- `WaitClickable(page *rod.Page, selector string, timeout time.Duration) error` — 等待元素可见且可点击（稳定状态）
- `WaitDOMReady(page *rod.Page, timeout time.Duration) error` — 等待页面 DOM 就绪

### 截图
- `FullPageScreenshot(page *rod.Page, filePath string) error` — 截取页面完整截图（含滚动区域），保存到指定路径
- `ElementScreenshot(element *rod.Element, filePath string) error` — 截取指定元素的截图
- `PageScreenshot(page *rod.Page, name string) error` — 截取页面完整截图，保存到配置的 `ScreenshotDir` 目录
- `ElementScreenshotToFile(element *rod.Element, name string) error` — 截取元素截图，保存到配置的 `ScreenshotDir` 目录

### CDP 监听
- `EnableConsoleMonitor(page *rod.Page) error` — 启用控制台监听（捕获 `console.error`、`console.warning` 和未捕获异常）
- `EnableNetworkMonitor(page *rod.Page) error` — 启用网络监听（捕获 `Network.loadingFailed` 事件）
- `GetConsoleErrors(page *rod.Page) []ConsoleError` — 获取收集的控制台错误
- `GetNetworkErrors(page *rod.Page) []NetworkError` — 获取收集的网络错误
- `AssertNoErrors(t TB, page *rod.Page)` — 断言页面没有控制台和网络错误（用于测试用例末尾验证）

### 功能选项
- `WithHeadless(v bool) Option` — 设置无头模式
- `WithTimeout(d time.Duration) Option` — 设置超时时间（浏览器或页面级别）
- `WithSmooth(b bool) Option` — 启用平滑滚动
- `WithConsoleMonitor() Option` — 启用页面控制台监听
- `WithNetworkMonitor() Option` — 启用页面网络监听

## 编写 E2E 测试

rodhelper 的测试套件遵循以下模式，完整示例参考 [`e2etest/web_app_example/`](e2etest/web_app_example/)：

### 测试模式

1. **TestMain** 统一管理生命周期：先启动测试 Web 服务器，再启动浏览器实例，运行所有子测试后按逆序清理（关闭浏览器 → 关闭服务器 → 清理临时文件）。
2. **setupTest** 辅助函数为每个测试用例创建新页面，通过 `t.Cleanup` 注册页面关闭。
3. 每个测试用例结束时调用 `rodhelper.AssertNoErrors(t, page)` 验证测试过程中无意外控制台错误或网络请求失败。
4. 所有测试通过 `t.Run` 组织为子测试，共享全局浏览器实例。

### 示例框架

```go
func TestExample(t *testing.T) {
    page := setupTest(t)

    // 执行操作
    elem, _ := rodhelper.FindElement(page, "#submit-btn")
    _ = rodhelper.Click(elem)

    // 验证结果
    rodhelper.AssertNoErrors(t, page)
}
```

### 测试覆盖的交互类型

`e2etest/web_app_example/` 的 27 个测试文件覆盖了以下交互类型（每个测试文件对应一个或多个场景）：

基础交互：链接跳转、表单填写与验证、键盘事件、hover 悬浮效果、文件上传、文件下载  
容器交互：弹窗（Dialog）、模态框（Modal）、折叠面板（Accordion）、标签页（Tabs）、轮播（Carousel）、iFrame  
数据交互：分页（Pagination）、无限滚动（InfiniteScroll）、实时搜索（LiveSearch）、Toast 提示  
视觉与动效：动画（Animation）、响应式布局（Responsive）、滚动（Scrolling）  
高级：拖放（Drag & Drop）、存储（Storage）、错误捕获（Error Capture）、水印（Waterfall）、加载状态（Loading）

## Windows 注意事项

rodhelper 针对 Windows 环境内置了以下自动处理：

- **启动参数**：自动添加 `--disable-gpu` 和 `--no-sandbox` 浏览器启动参数
- **浏览器降级**：rod 下载失败时自动降级使用本机已安装的 Chrome 或 Edge
- **进程清理**：通过 Job Object 实现进程组管理，确保无僵尸进程残留
- **Unicode 路径**：完整支持中文用户名等 Unicode 路径场景
- **高 DPI**：自动检测高 DPI 缩放并调整视口参数
- **企业代理**：自动检测企业代理配置并应用到浏览器启动参数