ohos-playwright 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 social4hyq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# ohos-playwright
+
+让 Playwright 在 OpenHarmony 上跑 e2e —— 接管设备上的系统浏览器（ArkWeb，Chromium 内核）。同一份 `playwright.config.ts` 和 spec 在 Windows / Linux / macOS 上仍按原版 Playwright 跑，**不需要写两份**。
+
+## 它解决什么问题
+
+OpenHarmony 上没有官方的 Playwright：没有适配的浏览器二进制可下载，Playwright 自己的平台检测在 OpenHarmony 上直接崩。
+
+ohos-playwright 换了个思路 —— **不让 Playwright 自己启动浏览器**，而是通过 `hdc` 把设备上正在运行的系统浏览器的调试通道转发回本机，让 Playwright "接管"它。spec 文件一行不动，`playwright.config.ts` 只多一层包装；CI / 本地 / 鸿蒙开发机共用同一份配置。
+
+## 快速开始
+
+### 1. 安装
+
+```sh
+pnpm add -D ohos-playwright @playwright/test
+```
+
+> `@playwright/test` 是 peer dependency，版本 `>=1.59.0`。
+
+### 2. 包一层 config
+
+```ts
+// playwright.config.ts
+import { defineConfig, devices } 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 上会被自动裁掉，留着也不影响其他主机
+  ],
+  // ...其他正常的 Playwright 配置
+}))
+```
+
+非 OpenHarmony 主机上 `withOpenHarmony` 原样返回 config；OpenHarmony 上它会注入 setup/teardown、把 workers 锁 1、过滤掉 firefox/webkit。
+
+### 3. 改 npm script
+
+```json
+{ "scripts": { "test:e2e": "ohos-playwright test" } }
+```
+
+`ohos-playwright` 这个 bin 在非 OpenHarmony 上等价于 `playwright`，所有参数透传。
+
+### 4. spec 文件不用动
+
+```ts
+import { test, expect } from '@playwright/test'
+
+test('something', async ({ page }) => {
+  await page.goto('/')
+  await expect(page).toHaveTitle(/.../)
+})
+```
+
+### 5. 运行
+
+```sh
+pnpm test:e2e
+```
+
+第一次跑会自动找设备、拉起系统浏览器、转发调试端口、让 Playwright 接管。
+
+## 工作原理
+
+**非 OpenHarmony 主机**：什么都不做，等价于 stock Playwright，所以配置可以跨平台共用。
+
+**OpenHarmony 主机**：
+
+- **复用而非启动**：Playwright 不再自己起浏览器，而是接管设备上正在跑的系统浏览器，通过 `hdc` 把它的调试通道转发到本机。
+- **Spec 无感**：你写的还是 `@playwright/test`，底层透明替换为走 CDP 复用设备上现有 page 的实现。
+- **配置自动收紧**：`workers` 锁 1、firefox / webkit project 自动裁掉、globalSetup / globalTeardown 自动注入 —— 都由 `withOpenHarmony` 在 OpenHarmony 上完成，其他主机不受影响。
+- **设备没连会自救**：测试启动时如果设备没连，先 LAN 广播找设备并自动连上，找不到再弹提示。
+
+## 环境变量
+
+| 变量 | 默认 | 何时需要设 |
+| --- | --- | --- |
+| `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（dev server 端口不是 5173 必设） |
+| `OHOS_PW_INFO_PATH` | `os.tmpdir()/ohos-playwright-cdp.json` | 想固定 CDP info 文件位置（CI 多 job 隔离等） |
+| `OHOS_PW_AUTO_CONNECT` | （未设） | 设 `0` 跳过自动 discover / tconn 流程 |
+| `OHOS_PW_HOST` | 自动 | 内部标志位，**不要手动设** |
+
+## 约束
+
+设备和 ArkWeb 本身带来的硬约束，不是 ohos-playwright 能解决的：
+
+- **`workers: 1`**：设备上只有一个浏览器实例，多 worker 会互相抢同一份 localStorage / URL。
+- **不能并发 project**：firefox / webkit 在 ArkWeb 上跑不了，会被自动裁掉。
+- **不能 `newContext` / `newPage`**：全程复用一个 context、一个 page。要做用例隔离，用 `localStorage.clear()` + `page.reload()` 代替独立 context。
+- **测试结束不关浏览器**：浏览器进程归 OS 管，不归测试管。
+- **`process.platform` 在测试进程里被改成 `'linux'`**：如果你在 spec / fixture 里读 `process.platform` 做平台分支，会拿到 `'linux'`。判断真实主机身份请用 `process.env.OHOS_PW_HOST`。
+- **设备必须开发者模式 + 无线调试或 USB 调试**：自动连接依赖 `hdc discover`（UDP:8710），CI 上推荐预先 `hdc tconn`。
+
+## 排错
+
+| 报错 | 怎么处理 |
+| --- | --- |
+| `Cannot find module 'ohos-playwright/config'` | 没装或没 install，按"快速开始"重做 |
+| `defineConfig({...})` 没有类型提示 | `tsconfig` 的 `moduleResolution` 改成 `bundler` 或 `nodenext` |
+| `未发现设备...`（中文） | 设备上开「开发者选项 → 无线调试」；本机防火墙放行 UDP:8710；CI 上预先手动 `hdc tconn <ip:port>` |
+| `Failed to launch com.huawei.hmos.browser` | 设备上没装该浏览器，或 bundle name 不对，设 `OHOS_PW_BUNDLE` |
+| `DevTools socket not found for pid` | 该浏览器没暴露 CDP（不是所有 OpenHarmony 浏览器都启用了 devtools） |
+| `CDP probe failed` | `hdc fport` 转发没起来，`hdc fport ls` 看现有 ruler、`hdc fport rm` 清残留 |
+| `await page.goto('/foo')` 不拼 baseURL | 检查 `use.baseURL` 是否设了非空值 |
+
+## 兼容性
+
+- **Playwright**：`>=1.59.0`（测试覆盖 1.60）
+- **Node**：`>=24`（OpenHarmony 上只支持 Node 24+）
+- **OpenHarmony**：`hdc` 可用 + 系统浏览器暴露 CDP。已验证 `com.huawei.hmos.browser`（华为浏览器，Chromium 132）
+- **其他主机**：Windows / Linux / macOS 上自动降级为 stock Playwright，无副作用
+
+## 协议
+
+MIT

package/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: ohos-playwright-migrate
+description: Use when the user asks to make a project's Playwright e2e tests run on OpenHarmony / ArkWeb, or to "add ohos-playwright", "适配 OpenHarmony", "用 ohos-playwright 跑 e2e"，or when you see a Playwright config in a repo that's expected to support OpenHarmony but still uses stock `playwright test`.
+---
+
+# ohos-playwright 迁移 SKILL
+
+把一个使用 stock Playwright 的工程改造成可以在 OpenHarmony 上接管华为浏览器（ArkWeb）跑 e2e，同时**保持在 Windows / Linux / macOS 上的原行为不变**。整个适配在非 OpenHarmony 主机上自动降级为 no-op。
+
+## 适用场景（什么时候应该启动这个 SKILL）
+
+满足任一即可：
+
+- 用户明说"接入 ohos-playwright"、"适配 OpenHarmony e2e"、"让 Playwright 在鸿蒙上跑"。
+- 工程根目录有 `playwright.config.ts` / `playwright.config.js`，并且工程目标平台包含 OpenHarmony。
+- 工程在 OpenHarmony 上跑 `playwright test` 直接报 `<unknown>` 平台 / 找不到浏览器二进制。
+
+不要启动这个 SKILL 的场景：
+
+- 工程不用 Playwright（比如 Cypress / WebdriverIO）。
+- 用户只想在 Linux/macOS/Windows 上跑 Playwright，并不关心鸿蒙。
+
+## 前置检查（动手前必须确认）
+
+1. **包管理器**：检查 `pnpm-lock.yaml` / `package-lock.json` / `yarn.lock` 确定是 pnpm / npm / yarn 中的哪一个。后续 `pnpm add` / `npm install` / `yarn add` 命令对应替换。
+2. **是否 workspace**：根目录有 `pnpm-workspace.yaml` 或 `package.json` 里有 `workspaces` 字段 → 是 monorepo。如果 `ohos-playwright` 已作为 workspace 包存在，依赖应该写 `"ohos-playwright": "workspace:*"` 而不是从 registry 装。
+3. **现有 Playwright 版本**：`@playwright/test` 必须 ≥ 1.59.0（`ohos-playwright` 的 peerDependency 下限）。低于的话先升级。
+4. **Node 版本**：`ohos-playwright` 的 `engines.node` 是 `>=24`（OpenHarmony 上只支持 Node 24+）。低于的话先升级，否则 install 时会有 EBADENGINE 警告，运行时也可能崩。
+5. **现有 config 形态**：读 `playwright.config.ts`，记录是 `defineConfig({...})` 还是 `defineConfig({...} satisfies PlaywrightTestConfig)`，是否已有 `globalSetup` / `globalTeardown` / `workers` 等字段。
+
+## 改造步骤
+
+按顺序做，每一步做完都跑验证再继续。
+
+### 步骤 1：安装 `ohos-playwright`
+
+- **workspace 内部**：在工程根 `package.json` 的 `devDependencies` 加 `"ohos-playwright": "workspace:*"`。
+- **独立工程**：`pnpm add -D ohos-playwright`（或对应包管理器命令）。
+
+然后跑一次安装让 bin 链接生效：
+
+```sh
+pnpm install
+```
+
+验证：`pnpm exec ohos-playwright --version` 能输出 Playwright 版本号。
+
+### 步骤 2：包装 `playwright.config.ts`
+
+最小改动：加两行，包一层。
+
+```ts
+import { defineConfig, devices } from '@playwright/test'
+import { withOpenHarmony } from 'ohos-playwright/config'
+
+export default defineConfig(withOpenHarmony({
+  // ...原有所有配置一字不动
+}))
+```
+
+**`withOpenHarmony` 的行为**：
+
+- 非 OpenHarmony 主机：原样返回 config，等于没包。
+- OpenHarmony 主机：
+  - `workers` 强制为 1（ArkWeb 单实例，多 worker 会抢同一份状态）。
+  - `globalSetup` / `globalTeardown` 注入为 `ohos-playwright/setup` / `ohos-playwright/teardown`。
+  - `projects` 过滤为只剩 `name === 'chromium'`（firefox / webkit 跑不了 ArkWeb）。
+
+**注意事项**：
+
+- 不要自己再写 `workers: 1` 或 `globalSetup` —— `withOpenHarmony` 在 OpenHarmony 上会覆盖。但在其他主机上你的写法保留，所以原本 `workers: process.env.CI ? 1 : undefined` 这类按主机逻辑可以保留。
+- 如果用户原本就有 `globalSetup`，迁移后会被 `withOpenHarmony` 覆盖。**不要默默覆盖** —— 把这个冲突告诉用户，让他决定：原 globalSetup 是否纯为 e2e 服务，能否放弃；如果不能，需要在 spec 启动前先手动调用其逻辑，或者改造 ohos-playwright/setup 的封装方式。
+- `projects` 数组里 chromium project 必须存在且 `name: 'chromium'`，否则 OpenHarmony 上没东西可跑。
+
+### 步骤 3：改 npm script
+
+`package.json` 里把 `test:e2e` 从 `playwright test` 换成 `ohos-playwright test`。其他参数（`--workers`、`--project`、`--grep` 等）原样保留 —— `ohos-playwright` 透传给 Playwright CLI。
+
+```json
+{
+  "scripts": {
+    "test:e2e": "ohos-playwright test"
+  }
+}
+```
+
+不要再加 `--workers=1` / `--project=chromium`，这些由 `withOpenHarmony` 在 OpenHarmony 上自动处理；在非 OH 主机上你也不希望被强制锁住。
+
+### 步骤 4：验证迁移
+
+按以下顺序验证：
+
+1. **类型检查**：跑工程现有的 type-check 命令（如 `pnpm typecheck` / `tsc --noEmit`）。`defineConfig(withOpenHarmony({...}))` 里的对象字面量应该有完整的 `PlaywrightTestConfig` 上下文类型；故意写一个错字段名应该报 `TS2353`。
+2. **列出测试**：`pnpm test:e2e --list`。
+   - 在 OpenHarmony 上：只应该出现 `[chromium]` 开头的用例。
+   - 在其他主机上：原本配置里的所有 project 都应该列出。
+3. **跑一遍全量**：`pnpm test:e2e`。
+   - OpenHarmony 上日志应该出现 `[ohos-playwright] browser pid=...` / `CDP ready: Chrome/...`。
+   - 浏览器进程在跑完后**不应该**被关闭（归 OS 管理）。
+
+## 用户自定义场景
+
+下面这些用户经常会问，预先准备好答案：
+
+### 设备上的 `hdc` 不在默认路径
+
+设置环境变量 `OHOS_PW_HDC`，例如 `OHOS_PW_HDC=/path/to/hdc pnpm test:e2e`。默认值 `/data/service/hnp/bin/hdc`。
+
+### 想接管别的浏览器 bundle
+
+设 `OHOS_PW_BUNDLE`，默认 `com.huawei.hmos.browser`。
+
+### dev server 端口不是 5173
+
+`withOpenHarmony` 会保留 `webServer` 配置和 `use.baseURL`，所以工程里改 dev server 端口正常生效。但浏览器**首次启动**时的导航 URL 由 `OHOS_PW_LAUNCH_URL` 控制，默认 `http://localhost:5173`，如果你的 dev server 不是这个端口，需要设这个环境变量。
+
+### CDP info 文件位置
+
+默认在 `os.tmpdir()/ohos-playwright-cdp.json`，setup 写、fixture 和 teardown 读。需要确定性位置就设 `OHOS_PW_INFO_PATH`。
+
+### spec 文件里用 `newContext` / `newPage`
+
+ArkWeb CDP **不实现** `Target.createBrowserContext`。fixture 复用 `browser.contexts()[0]` 和它已有的 page，所以 `page.context().newPage()` 会报错。改造 spec 使用 `localStorage.clear()` + `page.reload()` 实现隔离。
+
+### `hdc list targets` 返回 `[Empty]`（设备没连）
+
+setup 会自动救场：先 `hdc discover` 在 LAN 上 UDP 广播找听 TCP 的 daemon，找到就 `hdc tconn <ip:port>` 连上去。整套要求用户**在设备上**：① 进入「关于本机」连点版本号开启「开发者选项」；② 在「开发者选项」里启用「无线调试」；③ 设备与本机同 Wi-Fi；④ 本机防火墙放行 UDP:8710 入站。
+
+如果广播找不到设备：
+
+- 当前是 TTY → setup 用 readline 提示用户粘贴 `ip:port`，回车继续。
+- 非 TTY（CI / daemonized）→ 直接 `throw` 带步骤的中文提示。CI 上的正解是先在 host 上手动跑过 `hdc tconn <ip:port>`，让 hdc 把连接信息持久化。
+
+要完全跳过这套自动连接：设 `OHOS_PW_AUTO_CONNECT=0`，setup 会把"没设备"的报错让位给后续的 `hdc shell` 自己抛。
+
+## 排错
+
+| 症状 | 原因 | 处理 |
+| --- | --- | --- |
+| `Cannot find module 'ohos-playwright/config'` | 没装或没 `pnpm install` | 按步骤 1 重做 |
+| `defineConfig({...})` 里失去类型提示 | TS 没找到 `config.d.mts` | 确认 `moduleResolution` 是 `bundler` / `nodenext`；如果用的是 `node16` 老式解析，可能要在 `package.json` 的 exports 加 types 路径（包内已ship .d.mts，正常解析模式都能找到）|
+| `Failed to launch com.huawei.hmos.browser` | 设备上没装该浏览器，或 bundle name 不对 | 用 `OHOS_PW_BUNDLE` 改成实际的 bundle name |
+| `DevTools socket not found for pid` | 浏览器没开 devtools，或 `/proc/net/unix` 看不到 `webview_devtools_remote_<pid>` | 一般等几秒后 setup 会重试；持续失败说明 ArkWeb 版本不支持 CDP |
+| `CDP probe failed` | `hdc fport` 转发没生效 | 手动跑 `hdc fport ls` 看 ruler 是否存在；`hdc fport rm` 清掉残留后重试 |
+| `未发现设备。请在设备上：...` | 设备没连且 LAN 广播没找到 | 按提示在设备开「无线调试」；本机放行 UDP:8710；非 TTY 场景预先 `hdc tconn` |
+| `hdc tconn ... failed` | 网络不通 / 端口不对 / 设备拒绝 | 确认 ip:port 准确、双方同网段；设备屏幕上的端口可能每次启用无线调试都变 |
+| 用例里 `await page.goto('/foo')` 不拼 baseURL | fixture 包装漏了 | 检查 `playwright.config.ts` 的 `use.baseURL` 是否非空；fixture 只在 baseURL 存在时才包 `page.goto` |
+| OpenHarmony 上跑了一遍后 firefox/webkit 测试莫名跑不了 | 你没在 OpenHarmony 上，但 `process.env.OHOS_PW_HOST` 被遗留 | 这个 env var 由 `register.mjs` 在 OpenHarmony 上自动设；如果在其他主机看到它，说明误手动设置了 |
+
+## 不应该做的事
+
+- **不要**为了"让它跨平台"自己写 `process.platform === 'openharmony'` 的分支 —— `withOpenHarmony` + `register.mjs` 已经处理；register 在 OpenHarmony 上会把 `process.platform` 改成 `'linux'`，所以你的检测也会失效。要查"是不是 OpenHarmony 主机"用 `process.env.OHOS_PW_HOST`。
+- **不要**给 `playwright-core` 打 patch 来改 hostPlatform 检测。本包用进程级 `Object.defineProperty(process, 'platform', ...)` 代替，跨版本鲁棒。
+- **不要**手动管理 `hdc fport` 端口 —— setup 自己挑空闲端口、自己拆。
+- **不要**在测试结束后 `await browser.close()`。浏览器进程不归测试管。

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "ohos-playwright",
+  "version": "0.1.0",
+  "description": "Playwright adapter for OpenHarmony / ArkWeb via hdc + CDP",
+  "license": "MIT",
+  "author": "social4hyq",
+  "homepage": "https://github.com/social4hyq/ohos-playwright#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/social4hyq/ohos-playwright.git"
+  },
+  "bugs": {
+    "url": "https://github.com/social4hyq/ohos-playwright/issues"
+  },
+  "keywords": [
+    "playwright",
+    "openharmony",
+    "ohos",
+    "harmonyos",
+    "arkweb",
+    "e2e",
+    "hdc",
+    "cdp"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    "./fixture": "./src/fixture.mjs",
+    "./setup": "./src/setup.mjs",
+    "./teardown": "./src/teardown.mjs",
+    "./register": "./src/register.mjs",
+    "./loader": "./src/loader.mjs",
+    "./config": {
+      "types": "./src/config.d.mts",
+      "default": "./src/config.mjs"
+    }
+  },
+  "bin": {
+    "ohos-playwright": "src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "SKILL.md"
+  ],
+  "peerDependencies": {
+    "@playwright/test": ">=1.59.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const register = resolve(__dirname, 'register.mjs')
+
+// @playwright/test's exports map blocks direct subpath resolution to cli.js,
+// so resolve the main entry and walk up to the package root, then append it.
+const req = createRequire(import.meta.url)
+let pkgRoot = dirname(req.resolve('@playwright/test'))
+while (!existsSync(resolve(pkgRoot, 'package.json'))) pkgRoot = dirname(pkgRoot)
+const playwrightCli = resolve(pkgRoot, 'cli.js')
+
+const child = spawn(
+  process.execPath,
+  ['--import', register, playwrightCli, ...process.argv.slice(2)],
+  { stdio: 'inherit' },
+)
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal)
+  else process.exit(code ?? 1)
+})

package/src/config.d.mts

@@ -0,0 +1,3 @@
+import type { PlaywrightTestConfig } from '@playwright/test'
+
+export function withOpenHarmony(config: PlaywrightTestConfig): PlaywrightTestConfig

package/src/config.mjs

@@ -0,0 +1,23 @@
+// Wrap a base Playwright config so it transparently turns into an ArkWeb/CDP
+// run on OpenHarmony and stays stock everywhere else. Usage:
+//
+//   import { defineConfig, devices } from '@playwright/test'
+//   import { withOpenHarmony } from 'ohos-playwright/config'
+//
+//   export default defineConfig(withOpenHarmony({ ...baseConfig }))
+//
+// On non-OpenHarmony hosts the input config is returned unchanged.
+export function withOpenHarmony(config) {
+  // Consult OHOS_PW_HOST, not process.platform — register.mjs has already
+  // overwritten platform to 'linux' by the time this function runs.
+  if (!process.env.OHOS_PW_HOST) return config
+  return {
+    ...config,
+    // Single ArkWeb instance via CDP — workers must be 1.
+    workers: 1,
+    globalSetup: 'ohos-playwright/setup',
+    globalTeardown: 'ohos-playwright/teardown',
+    // ArkWeb only speaks Chromium CDP; drop firefox/webkit projects.
+    projects: config.projects?.filter((p) => p.name === 'chromium') ?? config.projects,
+  }
+}

package/src/fixture.mjs

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs'
+import { test as base, chromium } from '@playwright/test'
+import { INFO_PATH } from './info-path.mjs'
+
+function readEndpoint() {
+  return JSON.parse(readFileSync(INFO_PATH, 'utf8')).endpoint
+}
+
+export const test = base.extend({
+  browser: [
+    async ({}, use) => {
+      const browser = await chromium.connectOverCDP(readEndpoint())
+      await use(browser)
+      // Do not close — the underlying browser is managed by the OS, not by us.
+    },
+    { scope: 'worker' },
+  ],
+
+  context: async ({ browser }, use, testInfo) => {
+    // ArkWeb CDP doesn't implement Target.createBrowserContext, so newContext()
+    // would fail. Reuse the default context and force-feed baseURL into the
+    // private _options so internal URL resolution (toHaveURL, locators) works.
+    const ctx = browser.contexts()[0]
+    const baseURL = testInfo.project.use.baseURL
+    if (baseURL) ctx._options.baseURL = baseURL
+    await use(ctx)
+  },
+
+  page: async ({ context }, use, testInfo) => {
+    const pages = context.pages()
+    if (pages.length === 0) {
+      throw new Error('No pages in ArkWeb CDP context. Open a tab in the browser first.')
+    }
+    const page = pages.find((p) => p.url().startsWith('http://localhost')) ?? pages[0]
+
+    // page.goto resolves URLs against the frame, not _options, so it needs its
+    // own baseURL wrapper to make `/foo`-style relative paths work.
+    const baseURL = testInfo.project.use.baseURL
+    if (baseURL) {
+      const root = baseURL.replace(/\/$/, '')
+      const origGoto = page.goto.bind(page)
+      page.goto = (url, opts) => origGoto(url.startsWith('/') ? root + url : url, opts)
+    }
+
+    await use(page)
+  },
+})
+
+export { expect } from '@playwright/test'

package/src/info-path.mjs

@@ -0,0 +1,7 @@
+import { tmpdir } from 'node:os'
+import { resolve } from 'node:path'
+
+// Setup writes the CDP endpoint info here; fixture and teardown read from it.
+// Override with OHOS_PW_INFO_PATH if you need a deterministic location.
+export const INFO_PATH =
+  process.env.OHOS_PW_INFO_PATH ?? resolve(tmpdir(), 'ohos-playwright-cdp.json')

package/src/loader.mjs

@@ -0,0 +1,23 @@
+import { resolve as resolvePath, dirname } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const FIXTURE_URL = pathToFileURL(resolvePath(__dirname, 'fixture.mjs')).href
+
+const TARGET = '@playwright/test'
+
+// Match Playwright's default testMatch: *.spec.* or *.test.* with common
+// JS/TS extensions. Only files matching this pattern get '@playwright/test'
+// rewritten — user config (playwright.config.ts), helpers, and node_modules
+// stay on stock Playwright.
+const TEST_FILE = /\.(spec|test)\.[mc]?[tj]sx?$/
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier === TARGET) {
+    const parent = context.parentURL ?? ''
+    if (TEST_FILE.test(parent)) {
+      return nextResolve(FIXTURE_URL, context)
+    }
+  }
+  return nextResolve(specifier, context)
+}

package/src/register.mjs

@@ -0,0 +1,20 @@
+import { register } from 'node:module'
+
+// Adapter only activates on OpenHarmony — elsewhere this file is a no-op so
+// the same ohos-playwright entry point and the same playwright.config.ts can
+// run on Windows / Linux / macOS with stock Playwright.
+if (process.platform === 'openharmony') {
+  // Mark the run as OpenHarmony before we lie about the platform — any code
+  // downstream (notably withOpenHarmony in the user's config) should consult
+  // OHOS_PW_HOST instead of process.platform, which is about to read 'linux'.
+  process.env.OHOS_PW_HOST = '1'
+
+  // Playwright's hostPlatform detection only branches on linux/darwin/win32.
+  // On OpenHarmony it falls through to "<unknown>" and various code paths
+  // break. We connect over CDP and never touch Playwright's bundled browser
+  // binaries, so it's safe to advertise linux for the duration of this
+  // process.
+  Object.defineProperty(process, 'platform', { value: 'linux' })
+
+  register('./loader.mjs', import.meta.url)
+}

package/src/setup.mjs

@@ -0,0 +1,203 @@
+import { execSync } from 'node:child_process'
+import { writeFileSync, mkdirSync } from 'node:fs'
+import { createServer } from 'node:net'
+import { dirname } from 'node:path'
+import { createInterface } from 'node:readline'
+import http from 'node:http'
+import { INFO_PATH } from './info-path.mjs'
+
+const HDC = process.env.OHOS_PW_HDC ?? '/data/service/hnp/bin/hdc'
+const BUNDLE = process.env.OHOS_PW_BUNDLE ?? 'com.huawei.hmos.browser'
+const LAUNCH_URL = process.env.OHOS_PW_LAUNCH_URL ?? 'http://localhost:5173'
+
+function sh(cmd) {
+  return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+}
+
+function shellOnDevice(cmd) {
+  return sh(`${HDC} shell "${cmd.replace(/"/g, '\\"')}"`)
+}
+
+function findBrowserPid() {
+  const ps = shellOnDevice('ps -ef')
+  for (const line of ps.split('\n')) {
+    const parts = line.trim().split(/\s+/)
+    const cmd = parts[parts.length - 1]
+    if (cmd === BUNDLE) return parseInt(parts[1], 10)
+  }
+  return null
+}
+
+function launchBrowser() {
+  shellOnDevice(`aa start -b ${BUNDLE} -m entry -a MainAbility -U ${LAUNCH_URL}`)
+}
+
+function findDevToolsSocket(pid) {
+  const unix = shellOnDevice('cat /proc/net/unix')
+  const name = `webview_devtools_remote_${pid}`
+  return unix.includes(`@${name}`) ? name : null
+}
+
+function pickFreePort() {
+  return new Promise((res, rej) => {
+    const srv = createServer()
+    srv.listen(0, '127.0.0.1', () => {
+      const port = srv.address().port
+      srv.close((err) => (err ? rej(err) : res(port)))
+    })
+    srv.on('error', rej)
+  })
+}
+
+function setupForward(port, socketName) {
+  sh(`${HDC} fport tcp:${port} localabstract:${socketName}`)
+}
+
+function probeCdp(port) {
+  return new Promise((res) => {
+    const req = http.get(`http://127.0.0.1:${port}/json/version`, (r) => {
+      let body = ''
+      r.on('data', (c) => (body += c))
+      r.on('end', () => res({ ok: r.statusCode === 200, body }))
+    })
+    req.on('error', (e) => res({ ok: false, err: e.code }))
+    req.setTimeout(3000, () => {
+      req.destroy()
+      res({ ok: false, err: 'TIMEOUT' })
+    })
+  })
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+const IP_PORT_RE = /^(\d{1,3}\.){3}\d{1,3}:\d+$/
+
+function listTargets() {
+  // hdc emits literal '[Empty]' when no devices are connected.
+  return sh(`${HDC} list targets`)
+}
+
+function discoverDevices() {
+  // `hdc discover` broadcasts on UDP:8710 and blocks for a few seconds. Lines
+  // beginning with [Info] are noise; real entries are bare ip:port. Exit code
+  // is always 0 — parse stdout, don't trust status.
+  let out = ''
+  try {
+    out = execSync(`${HDC} discover`, {
+      encoding: 'utf8',
+      timeout: 6000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+  } catch (e) {
+    out = e.stdout?.toString() ?? ''
+  }
+  return out
+    .split('\n')
+    .map((s) => s.trim())
+    .filter((s) => IP_PORT_RE.test(s))
+}
+
+function tconn(addr) {
+  try {
+    const out = execSync(`${HDC} tconn ${addr}`, {
+      encoding: 'utf8',
+      timeout: 10000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    return out.includes('Connect OK')
+  } catch {
+    return false
+  }
+}
+
+function promptAddress() {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    rl.question('[ohos-playwright] paste device ip:port (Enter to abort): ', (ans) => {
+      rl.close()
+      resolve(ans.trim())
+    })
+  })
+}
+
+const CONNECT_HELP = [
+  '[ohos-playwright] 未发现设备。请在设备上：',
+  '  1) 进入「设置 → 关于本机」连点版本号开启「开发者选项」',
+  '  2) 进入「开发者选项」启用「无线调试」',
+  '  3) 确认设备与本机在同一 Wi-Fi 下',
+  '  4) 防火墙放行本机 UDP:8710 入站（hdc discover 广播用）',
+  '也可手动跑 `hdc tconn <ip:port>` 后重新启动测试。',
+  '若不希望自动连接，设 OHOS_PW_AUTO_CONNECT=0 跳过。',
+].join('\n')
+
+async function ensureDeviceConnected() {
+  if (process.env.OHOS_PW_AUTO_CONNECT === '0') return
+
+  if (listTargets() !== '[Empty]') return
+
+  console.log('[ohos-playwright] no device connected, broadcasting (hdc discover)...')
+  const found = discoverDevices()
+
+  if (found.length > 0) {
+    console.log(`[ohos-playwright] discovered: ${found.join(', ')}`)
+    for (const addr of found) {
+      console.log(`[ohos-playwright] hdc tconn ${addr}`)
+      if (tconn(addr) && listTargets() !== '[Empty]') return
+    }
+    console.warn('[ohos-playwright] discovered devices but none connected successfully')
+  }
+
+  if (!process.stdin.isTTY) throw new Error(CONNECT_HELP)
+
+  console.log(CONNECT_HELP)
+  const addr = await promptAddress()
+  if (!addr) throw new Error('[ohos-playwright] no device address provided; aborting.')
+  if (!IP_PORT_RE.test(addr)) {
+    throw new Error(`[ohos-playwright] "${addr}" is not a valid ip:port.`)
+  }
+  if (!tconn(addr)) throw new Error(`[ohos-playwright] hdc tconn ${addr} failed.`)
+  if (listTargets() === '[Empty]') {
+    throw new Error('[ohos-playwright] tconn reported OK but list targets is still empty.')
+  }
+  console.log(`[ohos-playwright] connected: ${addr}`)
+}
+
+export default async function globalSetup() {
+  await ensureDeviceConnected()
+  console.log(`[ohos-playwright] locating ${BUNDLE}...`)
+  let pid = findBrowserPid()
+  if (!pid) {
+    console.log('[ohos-playwright] browser not running, launching...')
+    launchBrowser()
+    for (let i = 0; i < 20 && !pid; i++) {
+      await sleep(500)
+      pid = findBrowserPid()
+    }
+    if (!pid) throw new Error(`Failed to launch ${BUNDLE}`)
+  }
+  console.log(`[ohos-playwright] browser pid=${pid}`)
+
+  let socket = findDevToolsSocket(pid)
+  for (let i = 0; i < 10 && !socket; i++) {
+    await sleep(500)
+    socket = findDevToolsSocket(pid)
+  }
+  if (!socket) throw new Error(`DevTools socket not found for pid ${pid}`)
+  console.log(`[ohos-playwright] socket=${socket}`)
+
+  const port = await pickFreePort()
+  setupForward(port, socket)
+  console.log(`[ohos-playwright] hdc fport tcp:${port} -> localabstract:${socket}`)
+
+  const probe = await probeCdp(port)
+  if (!probe.ok) throw new Error(`CDP probe failed: ${probe.err || probe.body}`)
+  const info = JSON.parse(probe.body)
+  console.log(`[ohos-playwright] CDP ready: ${info.Browser}`)
+
+  mkdirSync(dirname(INFO_PATH), { recursive: true })
+  writeFileSync(
+    INFO_PATH,
+    JSON.stringify({ port, pid, socket, endpoint: `http://127.0.0.1:${port}` }, null, 2),
+  )
+  console.log(`[ohos-playwright] wrote ${INFO_PATH}`)
+}

package/src/teardown.mjs

@@ -0,0 +1,24 @@
+import { execSync } from 'node:child_process'
+import { readFileSync, unlinkSync } from 'node:fs'
+import { INFO_PATH } from './info-path.mjs'
+
+const HDC = process.env.OHOS_PW_HDC ?? '/data/service/hnp/bin/hdc'
+
+export default async function globalTeardown() {
+  let info
+  try {
+    info = JSON.parse(readFileSync(INFO_PATH, 'utf8'))
+  } catch {
+    return
+  }
+  const ruler = `tcp:${info.port} localabstract:${info.socket}`
+  try {
+    execSync(`${HDC} fport rm "${ruler}"`, { stdio: ['ignore', 'pipe', 'pipe'] })
+    console.log(`[ohos-playwright] removed fport ${ruler}`)
+  } catch (e) {
+    console.warn(`[ohos-playwright] fport rm failed (non-fatal): ${e.message?.split('\n')[0]}`)
+  }
+  try {
+    unlinkSync(INFO_PATH)
+  } catch {}
+}