WebDriver 接入教程—Mac版-帮助中心-飞跨浏览器

本文说明飞跨 macOS 主控的本地自动化接口，以及配套的交互式 E2E 脚本使用方式。

## 1 前置条件

- 启动飞跨主控浏览器，并在主控页面完成登录。
- 使用接口期间保持主控浏览器运行。
- 本地接口默认监听 `http://127.0.0.1:10039`。若该端口被占用，客户端会按 13 递增尝试其他端口；此时应使用客户端实际监听的端口。

主控登录态校验成功后才会提供本地接口。接口仅绑定 `127.0.0.1`，但本机任意进程均可调用。

## 2 配置 Python 虚拟环境

当前 macOS E2E 脚本位于 `/private/tmp/webdriver_e2e_test_mac.py`。创建并激活独立的 Python 环境：

```
cd /private/tmp
python3 -m venv feikua-webdriver-venv
source feikua-webdriver-venv/bin/activate
python -m pip install --upgrade pip
python -m pip install requests selenium
```

结束后退出虚拟环境：

```
deactivate
```

## 3 使用 E2E 脚本

激活虚拟环境后，在脚本所在目录运行：

```
cd /private/tmp
source feikua-webdriver-venv/bin/activate
python webdriver_e2e_test_mac.py
```

脚本会依次：

1. 调用本地列表接口并打印店铺。
2. 接收店铺序号或 `shop_id`。
3. 调用启动接口，取得进程 ID 和 CDP 端口。
4. 等待 `http://127.0.0.1:<debugger_port>/json/version` 就绪。
5. 下载或查找匹配的 macOS ChromeDriver，连接 Selenium，默认打开百度。
6. 询问是否通过停止接口关闭店铺。

常用参数：
```
＃ 打开指定页面，不使用默认的百度。
python webdriver_e2e_test_mac.py --target-url https://example.com

＃ 使用另一个本地接口端口。
python webdriver_e2e_test_mac.py --base-url http://127.0.0.1:10052

＃ 使用已经下载的 ChromeDriver。
python webdriver_e2e_test_mac.py --chromedriver /path/to/chromedriver

＃ 脚本退出时保留店铺。
python webdriver_e2e_test_mac.py --keep-store-open
```

未指定 `--chromedriver` 时，脚本会按 CDP 返回的实际 Chrome 版本下载匹配的驱动到 `/private/tmp/.webdriver_drivers/`。使用 `--no-auto-download-driver` 可禁用自动下载； `--allow-selenium-manager` 则允许 Selenium Manager 自行查找或下载驱动。

`--keep-store-open` 会让脚本退出而店铺继续运行，主控仍会管理该店铺。之后使用下方的 停止接口关闭店铺。

## 4 本地接口

将示例中的 `f1279938319` 替换为列表接口返回的实际 `shop_id`。停止接口只能关闭由当前 主控实例通过启动接口打开的店铺；重启主控会清空这份内存记录。

### 4.1 获取店铺列表

```
curl -sS 'http://127.0.0.1:10039/api/external/webdriver/stores'
```

成功响应示例：

```
{
  "code": 0,
  "msg": "success",
  "data": {
    "stores": [
      {
        "shop_id": "f1279938319",
        "shop_name": "145测试",
        "status": "idle"
      }
    ]
  }
}
```

当前主控实例尚未通过启动接口打开该店铺时，`status` 为 `idle`；启动成功后为 `running`。

### 4.2 启动店铺

```
curl -sS -X POST 'http://127.0.0.1:10039/api/external/webdriver/stores/start' \
  -H 'Content-Type: application/json' \
  -d '{"shop_id":"f1279938319"}'
```

成功响应示例：

```
{
  "code": 0,
  "msg": "success",
  "data": {
    "shop_id": "f1279938319",
    "pid": 24326,
    "debugger_port": 53493,
    "core_version": "0.17.10"
  }
}
```

`debugger_port` 每次启动都会动态分配，供 CDP 或 Selenium 使用，不能假定为固定端口。实际 Chromium 版本可通过该端口读取：

```
curl -sS 'http://127.0.0.1:53493/json/version'
```

### 4.3 关闭店铺

使用 `--keep-store-open`，或在脚本的关闭询问中输入 `n` 后，可用以下命令彻底关闭店铺：

```
curl -sS -X POST 'http://127.0.0.1:10039/api/external/webdriver/stores/stop' \
  -H 'Content-Type: application/json' \
  -d '{"shop_id":"f1279938319"}'
```

成功响应示例：

```
{
  "code": 0,
  "msg": "success",
  "data": {
    "shop_id": "f1279938319"
  }
}
```

主控会终止该店铺的浏览器主进程并删除本地启动记录，关联的 Chromium 子进程会随店铺进程退出。