ohos-playwright 0.2.2 → 0.2.3

package/README.md

@@ -1,166 +1,82 @@
 # ohos-playwright
 
-让 Playwright 在 OpenHarmony / ArkWeb 上跑 e2e，同一份 `playwright.config.ts` 和 spec 在 Windows / Linux / macOS 上仍按原版 Playwright 跑，**不需要写两份**。
+Playwright adapter for **HarmonyOS / OpenHarmony ArkWeb** (Chromium 132-based) — runs your existing Playwright e2e suite against the device's system browser over CDP, no bundled browser binaries needed. Spec files don't change.
 
-## 它解决什么问题
+The MCP server counterpart lives at [`ohos-playwright-mcp`](https://github.com/social4hyq/ohos-playwright-mcp).
 
-OpenHarmony 上没有官方的 Playwright：没有适配的浏览器二进制，Playwright 的平台检测在 `openharmony` 上直接崩。
+## Why this exists
 
-ohos-playwright **不让 Playwright 自己启动浏览器**，而是通过 `hdc` 把设备上正在运行的系统浏览器的 CDP 调试通道转发回本机，让 Playwright "接管"它。spec 一行不动，config 只多一层包装。
+Playwright's bundled browsers don't ship for the `openharmony` platform, and ArkWeb's sandbox blocks the `AF_UNIX` sockets Playwright uses internally — running stock Playwright on a HarmonyOS PC just crashes. This adapter skips the binary download, uses `hdc` to attach to the browser that's already on the device, and drives it through the Chrome DevTools Protocol over a TCP forward. If the browser isn't running it's launched automatically; when the test run ends the `hdc` forward is cleaned up but the browser stays open.
 
-## 快速开始
+On Windows / macOS / Linux `withOpenHarmony` is a no-op and the config passes through to stock Playwright.
 
-### 1. 安装
+## Install
 
-```sh
+```bash
 pnpm add -D ohos-playwright @playwright/test
 ```
 
-> `@playwright/test` 是 peer dependency，版本 `>=1.59.0`。Node ≥ 24。
+Node ≥ 24. `hdc` must be on `PATH` and an OpenHarmony / HarmonyOS device reachable.
 
-### 2. 包一层 config
+## Wire it into playwright.config
 
 ```ts
-// playwright.config.ts
-import { defineConfig, devices } from '@playwright/test'
+import { defineConfig } from '@playwright/test'
 import { withOpenHarmony } from 'ohos-playwright/config'
 
-export default defineConfig(withOpenHarmony({
-  testDir: './e2e',
-  use: { baseURL: 'http://localhost:5173' },
-  projects: [
-    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
-    // firefox / webkit 在 OpenHarmony 上会被自动裁掉
-  ],
-}))
+export default defineConfig(withOpenHarmony({ /* your config */ }))
 ```
 
-`withOpenHarmony` 在非 OH 主机上原样返回 config；在 OH 上注入 setup/teardown、锁 workers=1、过滤非 chromium project。
-
-### 3. npm script
-
 ```json
 { "scripts": { "test:e2e": "ohos-playwright test" } }
 ```
 
-`ohos-playwright` 在非 OH 上等价于 `playwright`，所有参数透传。
-
-### 4. spec 不用动
-
-```ts
-import { test, expect } from '@playwright/test'
-
-test('something', async ({ page }) => {
-  await page.goto('/')
-  await expect(page).toHaveTitle(/.../)
-})
-```
+## Limitations
 
-### 5. 运行
+- **Chromium only.** firefox and webkit aren't available on HarmonyOS.
+- **One context, one page.** `newContext()` / `newPage()` aren't supported. Isolate tests with `localStorage.clear()` + `page.reload()`.
+- **`process.platform` reads `'linux'`** during the run — we patch it because Playwright's hostPlatform detection only branches on linux/darwin/win32 and falls through to `<unknown>` on openharmony. For real platform checks use `process.env.OHOS_PW_HOST`.
 
-```sh
-pnpm test:e2e
-```
+## Environment variables
 
-首次跑会自动找设备、拉起浏览器、转发 CDP 端口。如果本机就是 OpenHarmony 设备，会通过 `param get persist.hdc.port` 自动发现端口并连接，无需手动配置。
-
-## 工作原理
-
-**非 OpenHarmony 主机**：什么都不做，等价于 stock Playwright。
-
-**OpenHarmony 主机**：
-
-- **复用而非启动**：Playwright 不再自己起浏览器，接管设备上正在跑的系统浏览器，通过 `hdc` 把 CDP 通道转发到本机。
-- **Spec 无感**：底层透明替换 `@playwright/test` 导入，走 CDP 复用设备上现有 page。
-- **配置自动收紧**：`workers` 锁 1、firefox/webkit 裁掉、globalSetup/Teardown 自动注入。
-- **智能设备发现**（v0.2.0）：
-  1. 已有连接 → 直接复用
-  2. 本机就是 OH 设备 → 读 `persist.hdc.port` 秒连
-  3. LAN 广播 `hdc discover` → 找独立设备
-  4. 找不到 → TTY 提示手动输入 / CI 直接报错
+| Variable | Default |
+|---|---|
+| `OHOS_PW_BUNDLE` | `com.huawei.hmos.browser` |
+| `OHOS_PW_LAUNCH_URL` | `http://localhost:5173` |
+| `OHOS_PW_HDC` | `/data/service/hnp/bin/hdc` |
+| `OHOS_PW_AUTO_CONNECT` | auto (set `0` to skip device auto-connect) |
+| `OHOS_PW_INFO_PATH` | `<tmpdir>/ohos-playwright-cdp.json` |
 
-## 设备连接
+## Compatibility
 
-### 本机即设备（一台 OH 机器跑全部）
+| | Required |
+|---|---|
+| Node | ≥ 24 |
+| Playwright | ≥ 1.59 |
+| Verified browser | `com.huawei.hmos.browser` (Chromium 132) |
 
-无需额外配置，`ensureDeviceConnected()` 会自动通过 `param get persist.hdc.port` 连上本机 hdc 守护进程。
+## Troubleshooting
 
-### 固定无线调试端口（一劳永逸）
+**`Cannot find module 'ohos-playwright/config'`** — not installed, or `pnpm install` not run.
 
-无线调试每次开关端口都会变。设固定端口后不再需要看屏幕：
+**`defineConfig(...)` has no type hints** — set `moduleResolution` to `bundler` or `nodenext` in tsconfig.
 
-```sh
-# 先连上（USB 或看屏幕临时端口）
-hdc tconn 127.0.0.1:<临时端口>
+**`未发现设备` / no device found** — on the device, enable Developer Options → Wireless Debugging, make sure it's on the same Wi-Fi as the host, and allow inbound UDP:8710 (used by `hdc discover` broadcast). In CI, run `hdc tconn <ip:port>` manually before tests.
 
-# 设固定端口（会重启设备）
-hdc tmode port 5555
+**`Failed to launch` the browser** — bundle not installed or wrong bundle name. List installed browsers with:
 
-# 之后永远用固定端口
-hdc tconn 127.0.0.1:5555
 ```
-
-设好后 `param get persist.hdc.port` 也返回固定值，ohos-playwright 自动识别。
-
-### 跳过自动连接
-
-```sh
-OHOS_PW_AUTO_CONNECT=0 pnpm test:e2e
+hdc shell "bm dump -a" | grep -iE "browser|webview|chrom|arkweb"
 ```
 
-## 环境变量
-
-| 变量 | 默认值 | 说明 |
-|---|---|---|
-| `OHOS_PW_HDC` | `/data/service/hnp/bin/hdc` | hdc 二进制路径 |
-| `OHOS_PW_BUNDLE` | `com.huawei.hmos.browser` | 接管的目标浏览器 bundle |
-| `OHOS_PW_LAUNCH_URL` | `http://localhost:5173` | 浏览器首次启动时的导航 URL |
-| `OHOS_PW_INFO_PATH` | `os.tmpdir()/ohos-playwright-cdp.json` | CDP info 文件位置 |
-| `OHOS_PW_AUTO_CONNECT` | （未设） | 设为 `0` 跳过自动 discover/tconn 流程 |
-| `OHOS_PW_HOST` | 自动 | 内部标志位，**不要手动设** |
-
-## 约束
-
-设备和 ArkWeb 本身的硬约束：
-
-- **`workers: 1`**：设备上只有一个浏览器实例。
-- **不能并发 project**：firefox/webkit 在 ArkWeb 上跑不了，自动裁掉。
-- **不能 `newContext` / `newPage`**：全进程复用一个 context、一个 page。用例隔离用 `localStorage.clear()` + `page.reload()`。
-- **测试结束不关浏览器**：浏览器进程归 OS 管。
-- **`process.platform` 被改成 `'linux'`**：判断真实主机用 `process.env.OHOS_PW_HOST`。
-- **设备需要开发者模式 + 无线调试或 USB 调试**。
-
-## 排错
-
-| 报错 | 处理 |
-|---|---|
-| `Cannot find module 'ohos-playwright/config'` | 没装或没 install |
-| `defineConfig({...})` 没有类型提示 | `tsconfig` 的 `moduleResolution` 改成 `bundler` 或 `nodenext` |
-| `未发现设备...` | 设备上开「开发者选项 → 无线调试」；本机防火墙放行 UDP:8710；CI 预先 `hdc tconn` |
-| `Failed to launch com.huawei.hmos.browser` | 设备上没装该浏览器，或设 `OHOS_PW_BUNDLE` |
-| `DevTools socket not found for pid` | 浏览器没暴露 CDP，或等几秒重试 |
-| `CDP probe failed` | `hdc fport ls` 查现 ruler，`hdc fport rm` 清残留 |
-| `await page.goto('/foo')` 不拼 baseURL | 检查 `use.baseURL` 是否非空 |
-
-## TypeScript
-
-项目源码使用 TypeScript（`.mts`），Node 24 原生支持类型剥离，无需编译步骤。
-
-支持类型检查：
-
-```sh
-npm run typecheck   # tsc --noEmit
-```
+Then set `OHOS_PW_BUNDLE` (e.g. `OHOS_PW_BUNDLE=com.quark.ohosbrowser`).
 
-`withOpenHarmony` 从 `ohos-playwright/config` 导入时有完整的 `PlaywrightTestConfig` 类型提示（直接从源码推断，无需 `.d.ts` 文件）。
+**`DevTools socket not found`** — browser doesn't expose CDP, or hasn't finished loading. Usually a retry after a few seconds works; persistent failure means this browser doesn't support CDP.
 
-## 兼容性
+**`CDP probe failed`** — leftover `hdc` forward rule from a prior crashed run. `hdc fport ls` to inspect, `hdc fport rm tcp:<port> localabstract:<socket>` to clear.
 
-- **Playwright**：`>=1.59.0`
-- **Node**：`>=24`（OpenHarmony 上只支持 Node 24+）
-- **OpenHarmony**：`hdc` 可用 + 系统浏览器暴露 CDP。已验证 `com.huawei.hmos.browser`（华为浏览器，Chromium 132）
-- **其他主机**：Windows / Linux / macOS 上自动降级为 stock Playwright，无副作用
+**`page.goto('/foo')` doesn't prepend baseURL** — Playwright's standard behavior is `/foo` → `http://localhost:5173/foo`. If it's not working, check `use.baseURL` in `playwright.config.ts`.
 
-## 协议
+## License
 
-MIT
+MIT © 2026 social4hyq

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ohos-playwright",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Playwright adapter for OpenHarmony / ArkWeb via hdc + CDP",
   "license": "MIT",
   "author": "social4hyq",