ohos-playwright 0.1.1 → 0.2.1

package/README.md

@@ -1,12 +1,12 @@
 # ohos-playwright
 
-让 Playwright 在 OpenHarmony 上跑 e2e —— 接管设备上的系统浏览器（ArkWeb，Chromium 内核）。同一份 `playwright.config.ts` 和 spec 在 Windows / Linux / macOS 上仍按原版 Playwright 跑，**不需要写两份**。
+让 Playwright 在 OpenHarmony / ArkWeb 上跑 e2e，同一份 `playwright.config.ts` 和 spec 在 Windows / Linux / macOS 上仍按原版 Playwright 跑，**不需要写两份**。
 
 ## 它解决什么问题
 
-OpenHarmony 上没有官方的 Playwright：没有适配的浏览器二进制可下载，Playwright 自己的平台检测在 OpenHarmony 上直接崩。
+OpenHarmony 上没有官方的 Playwright：没有适配的浏览器二进制，Playwright 的平台检测在 `openharmony` 上直接崩。
 
-ohos-playwright 换了个思路 —— **不让 Playwright 自己启动浏览器**，而是通过 `hdc` 把设备上正在运行的系统浏览器的调试通道转发回本机，让 Playwright "接管"它。spec 文件一行不动，`playwright.config.ts` 只多一层包装；CI / 本地 / 鸿蒙开发机共用同一份配置。
+ohos-playwright **不让 Playwright 自己启动浏览器**，而是通过 `hdc` 把设备上正在运行的系统浏览器的 CDP 调试通道转发回本机，让 Playwright "接管"它。spec 一行不动，config 只多一层包装。
 
 ## 快速开始
 
@@ -16,7 +16,7 @@ ohos-playwright 换了个思路 —— **不让 Playwright 自己启动浏览器
 pnpm add -D ohos-playwright @playwright/test
 ```
 
-> `@playwright/test` 是 peer dependency，版本 `>=1.59.0`。
+> `@playwright/test` 是 peer dependency，版本 `>=1.59.0`。Node ≥ 24。
 
 ### 2. 包一层 config
 
@@ -30,23 +30,22 @@ export default defineConfig(withOpenHarmony({
   use: { baseURL: 'http://localhost:5173' },
   projects: [
     { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
-    // firefox / webkit 在 OpenHarmony 上会被自动裁掉，留着也不影响其他主机
+    // firefox / webkit 在 OpenHarmony 上会被自动裁掉
   ],
-  // ...其他正常的 Playwright 配置
 }))
 ```
 
-非 OpenHarmony 主机上 `withOpenHarmony` 原样返回 config；OpenHarmony 上它会注入 setup/teardown、把 workers 锁 1、过滤掉 firefox/webkit。
+`withOpenHarmony` 在非 OH 主机上原样返回 config；在 OH 上注入 setup/teardown、锁 workers=1、过滤非 chromium project。
 
-### 3. 改 npm script
+### 3. npm script
 
 ```json
 { "scripts": { "test:e2e": "ohos-playwright test" } }
 ```
 
-`ohos-playwright` 这个 bin 在非 OpenHarmony 上等价于 `playwright`，所有参数透传。
+`ohos-playwright` 在非 OH 上等价于 `playwright`，所有参数透传。
 
-### 4. spec 文件不用动
+### 4. spec 不用动
 
 ```ts
 import { test, expect } from '@playwright/test'
@@ -63,56 +62,101 @@ test('something', async ({ page }) => {
 pnpm test:e2e
 ```
 
-第一次跑会自动找设备、拉起系统浏览器、转发调试端口、让 Playwright 接管。
+首次跑会自动找设备、拉起浏览器、转发 CDP 端口。如果本机就是 OpenHarmony 设备，会通过 `param get persist.hdc.port` 自动发现端口并连接，无需手动配置。
 
 ## 工作原理
 
-**非 OpenHarmony 主机**：什么都不做，等价于 stock Playwright，所以配置可以跨平台共用。
+**非 OpenHarmony 主机**：什么都不做，等价于 stock Playwright。
 
 **OpenHarmony 主机**：
 
-- **复用而非启动**：Playwright 不再自己起浏览器，而是接管设备上正在跑的系统浏览器，通过 `hdc` 把它的调试通道转发到本机。
-- **Spec 无感**：你写的还是 `@playwright/test`，底层透明替换为走 CDP 复用设备上现有 page 的实现。
-- **配置自动收紧**：`workers` 锁 1、firefox / webkit project 自动裁掉、globalSetup / globalTeardown 自动注入 —— 都由 `withOpenHarmony` 在 OpenHarmony 上完成，其他主机不受影响。
-- **设备没连会自救**：测试启动时如果设备没连，先 LAN 广播找设备并自动连上，找不到再弹提示。
+- **复用而非启动**：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 直接报错
+
+## 设备连接
+
+### 本机即设备（一台 OH 机器跑全部）
+
+无需额外配置，`ensureDeviceConnected()` 会自动通过 `param get persist.hdc.port` 连上本机 hdc 守护进程。
+
+### 固定无线调试端口（一劳永逸）
+
+无线调试每次开关端口都会变。设固定端口后不再需要看屏幕：
+
+```sh
+# 先连上（USB 或看屏幕临时端口）
+hdc tconn 127.0.0.1:<临时端口>
+
+# 设固定端口（会重启设备）
+hdc tmode port 5555
+
+# 之后永远用固定端口
+hdc tconn 127.0.0.1:5555
+```
+
+设好后 `param get persist.hdc.port` 也返回固定值，ohos-playwright 自动识别。
+
+### 跳过自动连接
+
+```sh
+OHOS_PW_AUTO_CONNECT=0 pnpm test:e2e
+```
 
 ## 环境变量
 
-| 变量 | 默认 | 何时需要设 |
-| --- | --- | --- |
-| `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_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 本身带来的硬约束，不是 ohos-playwright 能解决的：
+设备和 ArkWeb 本身的硬约束：
 
-- **`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`。
+- **`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，按"快速开始"重做 |
+| 报错 | 处理 |
+|---|---|
+| `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` 是否设了非空值 |
+| `未发现设备...` | 设备上开「开发者选项 → 无线调试」；本机防火墙放行 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
+```
+
+`withOpenHarmony` 从 `ohos-playwright/config` 导入时有完整的 `PlaywrightTestConfig` 类型提示（直接从源码推断，无需 `.d.ts` 文件）。
 
 ## 兼容性
 
-- **Playwright**：`>=1.59.0`（测试覆盖 1.60）
+- **Playwright**：`>=1.59.0`
 - **Node**：`>=24`（OpenHarmony 上只支持 Node 24+）
 - **OpenHarmony**：`hdc` 可用 + 系统浏览器暴露 CDP。已验证 `com.huawei.hmos.browser`（华为浏览器，Chromium 132）
 - **其他主机**：Windows / Linux / macOS 上自动降级为 stock Playwright，无副作用

package/dist/cli.d.mts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.mjs

@@ -0,0 +1,44 @@
+#!/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';
+// Resolve @playwright/test from the consumer's project root (process.cwd()),
+// not from this package's own directory (which has no node_modules/ for its
+// peer dependencies when installed via a file: symlink).
+// noop.mjs doesn't need to exist on disk -- createRequire uses it only to
+// anchor the module resolution base path.
+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;
+try {
+    pwEntry = req.resolve('@playwright/test');
+}
+catch {
+    console.error(`[ohos-playwright] Cannot find @playwright/test from ${process.cwd()}.\n` +
+        'Make sure it is installed in the current project or an ancestor:\n' +
+        '  npm install -D @playwright/test\n' +
+        '  pnpm add -D @playwright/test');
+    process.exit(1);
+}
+let pkgRoot = dirname(pwEntry);
+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');
+// Node 24 has native TypeScript support; register.mts is resolved directly.
+const register = resolve(import.meta.dirname, 'register.mjs');
+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/dist/config.d.mts

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

package/dist/config.mjs

@@ -0,0 +1,24 @@
+// 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/dist/fixture.d.mts

@@ -0,0 +1,2 @@
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export { expect } from '@playwright/test';

package/dist/fixture.mjs

@@ -0,0 +1,44 @@
+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);
+        },
+        { scope: 'worker' },
+    ],
+    context: async ({ browser }, use, testInfo) => {
+        const ctx = browser.contexts()[0];
+        const baseURL = testInfo.project.use.baseURL;
+        if (baseURL) {
+            try {
+                const opts = ctx._options;
+                if (opts && typeof opts === 'object')
+                    opts.baseURL = baseURL;
+            }
+            catch (e) {
+                console.warn(`[ohos-playwright] Failed to inject baseURL: ${e instanceof Error ? e.message : e}`);
+            }
+        }
+        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 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, opts) => origGoto((url.startsWith('/') && !url.startsWith('//')) ? root + url : url, opts));
+        }
+        await use(page);
+    },
+});
+export { expect } from '@playwright/test';

package/dist/info-path.d.mts

@@ -0,0 +1,7 @@
+export declare const INFO_PATH: string;
+export interface CdpInfo {
+    port: number;
+    pid: number;
+    socket: string;
+    endpoint: string;
+}

package/dist/info-path.mjs

@@ -0,0 +1,5 @@
+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/dist/loader.d.mts

@@ -0,0 +1,15 @@
+interface ResolveContext {
+    parentURL?: string;
+    [key: string]: unknown;
+}
+interface NextResolve {
+    (specifier: string, context: ResolveContext): {
+        url: string;
+    } | Promise<{
+        url: string;
+    }>;
+}
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<{
+    url: string;
+}>;
+export {};

package/dist/loader.mjs

@@ -0,0 +1,20 @@
+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';
+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;
+export async function resolve(specifier, context, nextResolve) {
+    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/dist/register.d.mts

@@ -0,0 +1 @@
+export {};

package/dist/register.mjs

@@ -0,0 +1,17 @@
+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/dist/setup.d.mts

@@ -0,0 +1,13 @@
+interface RetryOptions {
+    max?: number;
+    interval?: number;
+    label?: string;
+}
+export declare function retry<T>(fn: () => T | Promise<T>, { max, interval, label }?: RetryOptions): Promise<T>;
+export declare function findBrowserPid(): number | null;
+export declare function hasDeviceConnected(): boolean;
+export declare function discoverDevices(): string[];
+export declare function tryLocalDevice(): boolean;
+export declare function ensureDeviceConnected(): Promise<void>;
+export default function globalSetup(): Promise<void>;
+export {};

package/dist/setup.mjs

@@ -0,0 +1,219 @@
+import { execFileSync } 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';
+const HDC_OPTS = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] };
+function hdc(args, opts) {
+    return String(execFileSync(HDC, args, { ...HDC_OPTS, ...opts })).trim();
+}
+function shellOnDevice(cmd) { return hdc(['shell', cmd]); }
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Exponential backoff: 100ms → 200ms → 400ms … capped at `interval` (default 1000ms).
+export async function retry(fn, { max = 10, interval = 1000, label = '' } = {}) {
+    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() {
+    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() {
+    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() {
+    shellOnDevice(`aa start -b ${BUNDLE} -m entry -a MainAbility -U ${LAUNCH_URL}`);
+}
+function findDevToolsSocket(pid, cachedUnix) {
+    const unix = cachedUnix ?? 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 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, socketName) {
+    const ruler = `tcp:${port} localabstract:${socketName}`;
+    try {
+        hdc(['fport', 'rm', ruler]);
+    }
+    catch { }
+    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 b = '';
+            r.on('data', (c) => (b += c));
+            r.on('end', () => res({ ok: r.statusCode === 200, body: b }));
+        });
+        req.on('error', (e) => 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() { return hdc(['list', 'targets']); }
+export function hasDeviceConnected() {
+    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() {
+    let out = '';
+    try {
+        out = hdc(['discover'], { timeout: 3000 });
+    }
+    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 {
+        return hdc(['tconn', addr], { timeout: 10000 }).includes('Connect OK');
+    }
+    catch {
+        return false;
+    }
+}
+function promptAddress() {
+    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() {
+    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() {
+    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() {
+    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}` });
+    }
+    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 = 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}` });
+    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/dist/teardown.d.mts

@@ -0,0 +1 @@
+export default function globalTeardown(): Promise<void>;

package/dist/teardown.mjs

@@ -0,0 +1,31 @@
+import { execFileSync } 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 {
+        execFileSync(HDC, ['fport', 'rm', ruler], { stdio: ['ignore', 'pipe', 'pipe'] });
+        console.log(`[ohos-playwright] removed fport ${ruler}`);
+    }
+    catch (e) {
+        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) {
+        const err = e;
+        if (err.code !== 'ENOENT') {
+            console.warn(`[ohos-playwright] Failed to remove ${INFO_PATH}: ${err.message}`);
+        }
+    }
+}