ohos-playwright 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ohos-playwright",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Playwright adapter for OpenHarmony / ArkWeb via hdc + CDP",
   "license": "MIT",
   "author": "social4hyq",
@@ -24,33 +24,35 @@
   ],
   "type": "module",
   "scripts": {
-    "test": "node --test src/loader.test.mjs"
+    "test": "node --test src/*.test.mts",
+    "typecheck": "tsc --noEmit"
   },
   "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"
-    }
+    "./fixture": "./src/fixture.mts",
+    "./setup": "./src/setup.mts",
+    "./teardown": "./src/teardown.mts",
+    "./register": "./src/register.mts",
+    "./loader": "./src/loader.mts",
+    "./config": "./src/config.mts"
   },
   "bin": {
-    "ohos-playwright": "src/cli.mjs"
+    "ohos-playwright": "./src/cli.mts"
   },
   "files": [
     "src",
-    "!src/*.test.mjs",
-    "SKILL.md"
+    "!src/*.test.mts"
   ],
   "peerDependencies": {
     "@playwright/test": ">=1.59.0"
   },
+  "devDependencies": {
+    "@playwright/test": ">=1.59.0",
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true

package/src/{cli.mjs → cli.mts}

@@ -13,7 +13,7 @@ const req = createRequire(resolve(process.cwd(), 'noop.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.
-let pwEntry
+let pwEntry: string
 try {
   pwEntry = req.resolve('@playwright/test')
 } catch {
@@ -26,10 +26,21 @@ try {
   process.exit(1)
 }
 let pkgRoot = dirname(pwEntry)
-while (!existsSync(resolve(pkgRoot, 'package.json'))) pkgRoot = dirname(pkgRoot)
+let levels = 0
+while (!existsSync(resolve(pkgRoot, 'package.json')) && levels++ < 50) {
+  pkgRoot = dirname(pkgRoot)
+}
+if (!existsSync(resolve(pkgRoot, 'package.json'))) {
+  console.error(
+    `[ohos-playwright] Cannot find @playwright/test package.json (walked up from ${dirname(pwEntry)}). ` +
+    'Please verify @playwright/test is correctly installed.',
+  )
+  process.exit(1)
+}
 const playwrightCli = resolve(pkgRoot, 'cli.js')
 
-const register = resolve(import.meta.dirname, 'register.mjs')
+// Node 24 has native TypeScript support; register.mts is resolved directly.
+const register = resolve(import.meta.dirname!, 'register.mts')
 
 const child = spawn(
   process.execPath,

package/src/{config.mjs → config.mts}

@@ -1,3 +1,5 @@
+import type { PlaywrightTestConfig } from '@playwright/test'
+
 // Wrap a base Playwright config so it transparently turns into an ArkWeb/CDP
 // run on OpenHarmony and stays stock everywhere else. Usage:
 //
@@ -7,7 +9,7 @@
 //   export default defineConfig(withOpenHarmony({ ...baseConfig }))
 //
 // On non-OpenHarmony hosts the input config is returned unchanged.
-export function withOpenHarmony(config) {
+export function withOpenHarmony(config: PlaywrightTestConfig): PlaywrightTestConfig {
   // 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

package/src/fixture.mts

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs'
+import { test as base, chromium } from '@playwright/test'
+import type { Browser, BrowserContext, Page } from '@playwright/test'
+import { INFO_PATH, type CdpInfo } from './info-path.mts'
+
+function readEndpoint(): string {
+  return (JSON.parse(readFileSync(INFO_PATH, 'utf8')) as CdpInfo).endpoint
+}
+
+export const test = base.extend({
+  browser: [
+    async ({}, use: (b: Browser) => Promise<void>) => {
+      const browser = await chromium.connectOverCDP(readEndpoint())
+      await use(browser)
+    },
+    { scope: 'worker' as const },
+  ],
+
+  context: async (
+    { browser }: { browser: Browser },
+    use: (c: BrowserContext) => Promise<void>,
+    testInfo: { project: { use: { baseURL?: string } } },
+  ) => {
+    const ctx = browser.contexts()[0]
+    const baseURL = testInfo.project.use.baseURL
+    if (baseURL) {
+      try {
+        const opts = (ctx as unknown as Record<string, unknown>)._options as Record<string, unknown> | undefined
+        if (opts && typeof opts === 'object') opts.baseURL = baseURL
+      } catch (e: unknown) {
+        console.warn(`[ohos-playwright] Failed to inject baseURL: ${e instanceof Error ? e.message : e}`)
+      }
+    }
+    await use(ctx)
+  },
+
+  page: async (
+    { context }: { context: BrowserContext },
+    use: (p: Page) => Promise<void>,
+    testInfo: { project: { use: { baseURL?: string } } },
+  ) => {
+    const pages = context.pages()
+    if (pages.length === 0) throw new Error('No pages in ArkWeb CDP context. Open a tab first.')
+    const page = pages.find((p) => p.url().startsWith('http://localhost')) ?? pages[0]
+
+    const baseURL = testInfo.project.use.baseURL
+    if (baseURL) {
+      const root = baseURL.replace(/\/+$/, '')
+      const origGoto = page.goto.bind(page)
+      page.goto = ((url: string, opts?: Record<string, unknown>) =>
+        origGoto((url.startsWith('/') && !url.startsWith('//')) ? root + url : url, opts)
+      ) as typeof page.goto
+    }
+
+    await use(page)
+  },
+})
+
+export { expect } from '@playwright/test'

package/src/{info-path.mjs → info-path.mts}

@@ -3,5 +3,12 @@ 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 =
+export const INFO_PATH: string =
   process.env.OHOS_PW_INFO_PATH ?? resolve(tmpdir(), 'ohos-playwright-cdp.json')
+
+export interface CdpInfo {
+  port: number
+  pid: number
+  socket: string
+  endpoint: string
+}

package/src/loader.mts

@@ -0,0 +1,31 @@
+import { resolve as resolvePath } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const FIXTURE_URL = pathToFileURL(resolvePath(import.meta.dirname!, 'fixture.mts')).href
+const TARGET = '@playwright/test'
+const TEST_FILE = /\.(spec|test)\.[mc]?[tj]sx?$/
+const PACKAGE_ROOT_URL = pathToFileURL(resolvePath(import.meta.dirname!, '..') + '/').href
+const PROJECT_ANCHOR = pathToFileURL(resolvePath(process.cwd(), 'noop.mjs')).href
+
+interface ResolveContext { parentURL?: string; [key: string]: unknown }
+interface NextResolve {
+  (specifier: string, context: ResolveContext): { url: string } | Promise<{ url: string }>
+}
+
+export async function resolve(
+  specifier: string,
+  context: ResolveContext,
+  nextResolve: NextResolve,
+): Promise<{ url: string }> {
+  if (specifier === TARGET) {
+    const parent = context.parentURL ?? ''
+    if (TEST_FILE.test(parent)) {
+      const result = await nextResolve(FIXTURE_URL, context)
+      return { url: result.url }
+    }
+    if (parent.startsWith(PACKAGE_ROOT_URL)) {
+      return nextResolve(specifier, { ...context, parentURL: PROJECT_ANCHOR })
+    }
+  }
+  return nextResolve(specifier, context)
+}

package/src/{register.mjs → register.mts}

@@ -3,7 +3,7 @@ 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') {
+if ((process.platform as string) === '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'.
@@ -16,5 +16,5 @@ if (process.platform === 'openharmony') {
   // process.
   Object.defineProperty(process, 'platform', { value: 'linux' })
 
-  register('./loader.mjs', import.meta.url)
+  register('./loader.mts', import.meta.url)
 }

package/src/setup.mts

@@ -0,0 +1,224 @@
+import { execFileSync, type ExecFileSyncOptions } 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.mts'
+
+const HDC: string = process.env.OHOS_PW_HDC ?? '/data/service/hnp/bin/hdc'
+const BUNDLE: string = process.env.OHOS_PW_BUNDLE ?? 'com.huawei.hmos.browser'
+const LAUNCH_URL: string = process.env.OHOS_PW_LAUNCH_URL ?? 'http://localhost:5173'
+
+const HDC_OPTS: ExecFileSyncOptions = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] } as const
+
+function hdc(args: string[], opts?: Partial<ExecFileSyncOptions>): string {
+  return String(execFileSync(HDC, args, { ...HDC_OPTS, ...opts })).trim()
+}
+
+function shellOnDevice(cmd: string): string { return hdc(['shell', cmd]) }
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
+
+interface RetryOptions { max?: number; interval?: number; label?: string }
+
+// Exponential backoff: 100ms → 200ms → 400ms … capped at `interval` (default 1000ms).
+export async function retry<T>(
+  fn: () => T | Promise<T>,
+  { max = 10, interval = 1000, label = '' }: RetryOptions = {},
+): Promise<T> {
+  for (let i = 0; i < max; i++) {
+    try { const r = await fn(); if (r) return r } catch {}
+    if (i < max - 1) {
+      const delay = Math.min(100 * Math.pow(2, i), interval)
+      await sleep(delay)
+    }
+  }
+  throw new Error(label ? `${label}: exhausted retries (${max} attempts)` : `retry exhausted after ${max} attempts`)
+}
+
+// Batch ps + /proc/net/unix into a single hdc shell call — avoids two
+// subprocess spawns and transfers.
+function fetchDeviceState(): { ps: string; unix: string } {
+  const raw = shellOnDevice('ps -o pid,args; echo "---SOCKET---"; cat /proc/net/unix')
+  const [ps, unix] = raw.split('---SOCKET---')
+  return { ps: ps || '', unix: unix || '' }
+}
+
+export function findBrowserPid(): number | null {
+  const { ps } = fetchDeviceState()
+  for (const line of ps.split('\n')) {
+    const t = line.trim()
+    if (!t) continue
+    const s = t.indexOf(' ')
+    if (s === -1) continue
+    if (t.slice(s + 1).includes(BUNDLE)) {
+      const pid = parseInt(t.slice(0, s), 10)
+      if (!Number.isNaN(pid)) return pid
+    }
+  }
+  return null
+}
+
+function launchBrowser(): void {
+  shellOnDevice(`aa start -b ${BUNDLE} -m entry -a MainAbility -U ${LAUNCH_URL}`)
+}
+
+function findDevToolsSocket(pid: number, cachedUnix?: string): string | null {
+  const unix = cachedUnix ?? shellOnDevice('cat /proc/net/unix')
+  const name = `webview_devtools_remote_${pid}`
+  return unix.includes(`@${name}`) ? name : null
+}
+
+function pickFreePort(): Promise<number> {
+  return new Promise((res, rej) => {
+    const srv = createServer()
+    srv.listen(0, '127.0.0.1', () => {
+      const a = srv.address()
+      if (a && typeof a === 'object') srv.close((e) => e ? rej(e) : res(a.port))
+      else srv.close(() => rej(new Error('Failed to get port')))
+    })
+    srv.on('error', rej)
+  })
+}
+
+function setupForward(port: number, socketName: string): void {
+  const ruler = `tcp:${port} localabstract:${socketName}`
+  try { hdc(['fport', 'rm', ruler]) } catch {}
+  hdc(['fport', 'tcp:' + port, 'localabstract:' + socketName])
+}
+
+interface CdpProbeResult { ok: boolean; err?: string; body?: string }
+
+function probeCdp(port: number): Promise<CdpProbeResult> {
+  return new Promise((res) => {
+    const req = http.get(`http://127.0.0.1:${port}/json/version`, (r) => {
+      let b = ''
+      r.on('data', (c: string) => (b += c))
+      r.on('end', () => res({ ok: r.statusCode === 200, body: b }))
+    })
+    req.on('error', (e: NodeJS.ErrnoException) => res({ ok: false, err: e.code }))
+    req.setTimeout(2000, () => { req.destroy(); res({ ok: false, err: 'TIMEOUT' }) })
+  })
+}
+
+const IP_PORT_RE = /^(\d{1,3}\.){3}\d{1,3}:\d+$/
+
+function listTargets(): string { return hdc(['list', 'targets']) }
+
+export function hasDeviceConnected(): boolean {
+  const t = listTargets()
+  return t.length > 0 && t !== '[Empty]'
+}
+
+// discoverDevices timeout reduced from 6s to 3s — LAN broadcast on local
+// network should respond within 1-2s; longer wait is unlikely to help.
+export function discoverDevices(): string[] {
+  let out = ''
+  try { out = hdc(['discover'], { timeout: 3000 }) } catch (e: unknown) {
+    out = (e as { stdout?: Buffer | string }).stdout?.toString() ?? ''
+  }
+  return out.split('\n').map(s => s.trim()).filter(s => IP_PORT_RE.test(s))
+}
+
+function tconn(addr: string): boolean {
+  try { return hdc(['tconn', addr], { timeout: 10000 }).includes('Connect OK') } catch { return false }
+}
+
+function promptAddress(): Promise<string> {
+  return new Promise((res) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    rl.question('[ohos-playwright] paste device ip:port (Enter to abort): ', (a) => { rl.close(); res(a.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')
+
+export function tryLocalDevice(): boolean {
+  try {
+    const raw = String(execFileSync('param', ['get', 'persist.hdc.port'], { ...HDC_OPTS, timeout: 3000 })).trim()
+    const port = parseInt(raw, 10)
+    if (!port || port < 1 || port > 65535) return false
+    console.log(`[ohos-playwright] local device port from param: ${port}`)
+    const addr = `127.0.0.1:${port}`
+    if (tconn(addr) && hasDeviceConnected()) { console.log(`[ohos-playwright] connected: ${addr}`); return true }
+    console.warn(`[ohos-playwright] tconn ${addr} failed`)
+  } catch {}
+  return false
+}
+
+export async function ensureDeviceConnected(): Promise<void> {
+  if (process.env.OHOS_PW_AUTO_CONNECT === '0') return
+  if (hasDeviceConnected()) return
+  if (tryLocalDevice()) return
+
+  console.log('[ohos-playwright] no local device, broadcasting (hdc discover)...')
+  const found = discoverDevices()
+  for (const addr of found) {
+    console.log(`[ohos-playwright] hdc tconn ${addr}`)
+    if (tconn(addr) && hasDeviceConnected()) return
+  }
+  if (found.length > 0) console.warn('[ohos-playwright] discovered devices but none connected')
+
+  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 (!hasDeviceConnected()) throw new Error('[ohos-playwright] tconn reported OK but list targets still empty.')
+  console.log(`[ohos-playwright] connected: ${addr}`)
+}
+
+export default async function globalSetup(): Promise<void> {
+  await ensureDeviceConnected()
+  console.log(`[ohos-playwright] locating ${BUNDLE}...`)
+
+  // Batch ps + /proc/net/unix into a single hdc call.
+  let deviceState = fetchDeviceState()
+  let pid = findBrowserPid()
+
+  if (!pid) {
+    console.log('[ohos-playwright] browser not running, launching...')
+    launchBrowser()
+    // Backoff: 100, 200, 400, 800, 1000, 1000, … (max 20 attempts ≈ 10s total)
+    pid = await retry(findBrowserPid, { max: 20, interval: 1000, label: `Failed to launch ${BUNDLE}` }) as number
+  }
+  console.log(`[ohos-playwright] browser pid=${pid}`)
+
+  // Reuse the /proc/net/unix snapshot if it's fresh (same shell call as ps above).
+  // If we waited for browser launch, re-fetch since the socket may be new.
+  let unixCache: string | undefined = pid ? undefined : deviceState.unix
+  if (!unixCache) {
+    // Re-fetch device state to get fresh /proc/net/unix after browser launch
+    deviceState = fetchDeviceState()
+    unixCache = deviceState.unix
+  }
+
+  const socket = await retry(
+    () => findDevToolsSocket(pid, unixCache),
+    { max: 10, interval: 500, label: `DevTools socket not found for pid ${pid}` },
+  ) as string
+  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.mts

@@ -0,0 +1,30 @@
+import { execFileSync } from 'node:child_process'
+import { readFileSync, unlinkSync } from 'node:fs'
+import { INFO_PATH, type CdpInfo } from './info-path.mts'
+
+const HDC: string = process.env.OHOS_PW_HDC ?? '/data/service/hnp/bin/hdc'
+
+export default async function globalTeardown(): Promise<void> {
+  let info: CdpInfo
+  try {
+    info = JSON.parse(readFileSync(INFO_PATH, 'utf8'))
+  } catch {
+    return
+  }
+  const ruler = `tcp:${info.port} localabstract:${info.socket}`
+  try {
+    execFileSync(HDC, ['fport', 'rm', ruler], { stdio: ['ignore', 'pipe', 'pipe'] })
+    console.log(`[ohos-playwright] removed fport ${ruler}`)
+  } catch (e: unknown) {
+    const msg = e instanceof Error ? e.message?.split('\n')[0] : String(e)
+    console.warn(`[ohos-playwright] fport rm failed (non-fatal): ${msg}`)
+  }
+  try {
+    unlinkSync(INFO_PATH)
+  } catch (e: unknown) {
+    const err = e as NodeJS.ErrnoException
+    if (err.code !== 'ENOENT') {
+      console.warn(`[ohos-playwright] Failed to remove ${INFO_PATH}: ${err.message}`)
+    }
+  }
+}

package/SKILL.md

@@ -1,155 +0,0 @@
----
-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/src/config.d.mts

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

package/src/fixture.mjs

@@ -1,49 +0,0 @@
-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/loader.mjs

@@ -1,46 +0,0 @@
-import { resolve as resolvePath } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-const FIXTURE_URL = pathToFileURL(resolvePath(import.meta.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?$/
-
-// Compute the package root URL from the loader's own location.  Used below to
-// detect when the importing module lives inside ohos-playwright, regardless of
-// what the package directory is named or how it was installed (file: symlink,
-// pnpm store hash, etc.).  Trailing '/' is critical to avoid matching sibling
-// directories whose names happen to share the same prefix.
-const PACKAGE_ROOT_URL = pathToFileURL(resolvePath(import.meta.dirname, '..') + '/').href
-
-// Anchor URL in the consumer project root for ESM resolution fallback.
-// When ohos-playwright is a file: symlink, modules inside it can't resolve
-// peer dependencies from the consumer's node_modules. Overriding parentURL
-// to a file inside the project restores normal resolution.
-// noop.mjs doesn't need to exist on disk.
-// PROJECT_ANCHOR is computed once at module-load time.  By the time this
-// module is --import'ed (via register.mjs), process.cwd() is guaranteed to be
-// the directory where the user invoked ohos-playwright test — Node sets cwd
-// before running --import hooks.  Do NOT defer this to the resolve hook; the
-// string is needed for synchronous prefix matching in the hot path.
-const PROJECT_ANCHOR = pathToFileURL(resolvePath(process.cwd(), 'noop.mjs')).href
-
-export async function resolve(specifier, context, nextResolve) {
-  if (specifier === TARGET) {
-    const parent = context.parentURL ?? ''
-    if (TEST_FILE.test(parent)) {
-      // Spec files -> use custom ArkWeb fixture
-      return nextResolve(FIXTURE_URL, context)
-    }
-    if (parent.startsWith(PACKAGE_ROOT_URL)) {
-      // Internal modules (fixture.mjs, etc.) -> resolve from consumer project
-      return nextResolve(specifier, { ...context, parentURL: PROJECT_ANCHOR })
-    }
-  }
-  return nextResolve(specifier, context)
-}

package/src/setup.mjs

@@ -1,203 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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 {}
-}