ohos-playwright 0.3.3 → 0.3.5

package/README.md

@@ -69,15 +69,15 @@ The following Playwright APIs have been validated on ArkWeb / HarmonyOS 6.1 (Chr
 | WebSocket | `page.routeWebSocket()` (requires Playwright ≥ 1.48) — intercepts WebSocket connections |
 | Accessibility (CDP) | `newCDPSession` + `Accessibility.getFullAXTree` — returns the full AX node tree |
 | Navigation history | `page.goBack()`, `page.goForward()` — implemented via `history.back/forward()` + CDP polling; returns when the history index changes |
-| Hover events | `locator.hover()` — fires `mouseover` / `mouseenter` event listeners; CSS `:hover` pseudo-class is **not** activated (adapter uses JS dispatch, not a real pointer move) |
+| Hover events | `locator.hover()` — fires `mouseover` / `mouseenter` event listeners **and** activates the CSS `:hover` pseudo-class via the real `Input.dispatchMouseEvent` path. Falls back to JS-only dispatch (DOM events without `:hover`) if Playwright's `boundingBox()` hangs for more than 5 s. |
 | Locale (partial) | `emulateLocale(tag)` fixture — rewrites `navigator.language` / `navigator.languages` via `addInitScript`; does not affect HTTP `Accept-Language` or browser UI locale |
-| User-Agent (partial) | `emulateDevice({ userAgent })` — overrides `navigator.userAgent` for page scripts; call before `page.goto()` for the override to take effect. HTTP `User-Agent` request headers are not changed. |
+| User-Agent | `emulateDevice({ userAgent })` — overrides both `navigator.userAgent` and the outgoing HTTP `User-Agent` header; call before `page.goto()` for the override to take effect. (`context.setExtraHTTPHeaders({ 'User-Agent': ... })` does **not** override UA — ArkWeb preserves the browser default there.) |
 | Service Workers | `navigator.serviceWorker.register()` — works on HTTPS pages; `navigator.serviceWorker` is `undefined` on non-secure origins (`data:`, `about:blank`) as in all browsers |
 | Clipboard | `navigator.clipboard.writeText()` / `readText()` — works on HTTPS pages after `context.grantPermissions(['clipboard-read', 'clipboard-write'])`; unavailable on non-secure origins |
 
 ### `emulateDevice` fixture
 
-Because `newContext()` is not supported in connectOverCDP mode, device emulation is exposed as a Playwright fixture parameter backed by CDP `Emulation.*` commands.
+Because `newContext()` is not available in default single-context mode (see "Multi-context / multi-page" in Limitations), device emulation is exposed as a Playwright fixture parameter backed by CDP `Emulation.*` commands.
 
 ```ts
 import { test, expect } from '@playwright/test'
@@ -99,7 +99,7 @@ test('precise viewport', async ({ page, emulateDevice }) => {
 > **⚠️ `isMobile: true` does not produce a precise viewport on ArkWeb.**
 > When `Emulation.setDeviceMetricsOverride` is called with `mobile: true`, ArkWeb enables its mobile layout-viewport compatibility path and renders at the 980px default mobile layout viewport — the passed `width`/`height` are effectively ignored (`window.innerWidth` reads 980 regardless). `deviceScaleFactor` has no effect on this. Use `isMobile: false` when you need an exact pixel viewport.
 >
-> **`userAgent` override is JS-layer only.** Call `await emulateDevice({ userAgent: '...' })` before `page.goto(url)` — `navigator.userAgent` on the destination page will reflect the override. The HTTP `User-Agent` request header is not changed (ArkWeb does not honour CDP UA overrides for outgoing headers).
+> **`userAgent` override applies to both JS and HTTP layers.** Call `await emulateDevice({ userAgent: '...' })` before `page.goto(url)` — `navigator.userAgent` on the destination page will reflect the override, and the outgoing HTTP `User-Agent` header is rewritten as well. Use `emulateDevice` rather than `context.setExtraHTTPHeaders({ 'User-Agent': ... })` — the latter does not override UA on ArkWeb.
 
 ### `tap` fixture
 
@@ -121,10 +121,25 @@ Coordinates are CSS pixels relative to the viewport (same as `touchscreen.tap`).
 ## Limitations
 
 - **Chromium only.** firefox and webkit aren't available on HarmonyOS.
-- **`newPage()` after `browser.newContext()` throws.** The raw `browser.newContext()` call succeeds (returns an empty context, 0 pages) but `ctx.newPage()` fails with `Cannot read properties of undefined (reading '_page')`. ArkWeb's CDP `Target.createBrowserContext` / `Target.createTarget` aren't usable in `connectOverCDP` mode. Tests share one context and one page — isolate with `localStorage.clear()` + `page.reload()`. For device emulation use the `emulateDevice` fixture instead of `browser.newContext({ ...device })`.
+- **Multi-context / multi-page is opt-in.** By default the adapter intercepts `browser.newContext()` with a friendly error. The root cause: ArkWeb's `Target.createTarget` returns a target with `type: 'other'`, not `'page'`, so Playwright's `crBrowser._onAttachedToTarget` skips it and `ctx.newPage()` throws `Cannot read properties of undefined (reading '_page')`. To opt in, set `process.env.PW_CHROMIUM_ATTACH_TO_OTHER = '1'` **before** importing `@playwright/test` — Playwright's upstream escape hatch then treats `'other'` targets as pages and `browser.newContext()` / `ctx.newPage()` work normally. Trade-off: ArkWeb's internal `'other'` targets (shared workers, etc.) also get treated as pages, which can perturb tests that use `touchscreen.tap()` or `context.recordHar()`. For single-context tests (the common case) leave the env unset and isolate with `localStorage.clear()` + `page.reload()`. For device emulation use the `emulateDevice` fixture instead of `browser.newContext({ ...device })`.
+
+  **Multi-worker mode.** To run tests in parallel across multiple workers, two things are required together:
+
+  1. Set `PW_CHROMIUM_ATTACH_TO_OTHER=1` (enables `newContext()` as above).
+  2. Import `test` from `ohos-playwright/parallel` instead of `ohos-playwright`:
+
+  ```ts
+  import { test, expect } from 'ohos-playwright/parallel'
+  ```
+
+  The `ohos-playwright/parallel` fixture opens one ArkWeb context per **test** via `browser.newContext()` (test-scoped) and one page via `ctx.newPage()`. Both are closed after each test. Cookies and localStorage are fully isolated between tests. All ArkWeb workarounds (goBack/goForward, popup interception, hover, evaluate→pageerror) apply identically.
+
+  Trade-offs to be aware of:
+  - **`newContext()` serialises internally in ArkWeb.** Concurrent `newContext()` calls on the same CDP connection are safe (~100 ms for 3 at once). The apparent ~3.4 s bottleneck was from concurrent `connectOverCDP` calls (connection handshakes serialise), not context creation itself. More than ~4 workers may not yield additional throughput.
+  - **The default `ohos-playwright` fixture is not parallel-safe.** Its `context` fixture always returns `browser.contexts()[0]` — all workers would race on the same ArkWeb tab. If you set `workers > 1` with `PW_CHROMIUM_ATTACH_TO_OTHER=1` but keep the default `test` import, `withOpenHarmony()` will warn at startup.
 - **HTTP `User-Agent` header can be changed via CDP, but not via `setExtraHTTPHeaders`.** `Emulation.setUserAgentOverride` (sent by `emulateDevice({ userAgent })`) rewrites both `navigator.userAgent` and the outgoing HTTP UA header — call it before `page.goto()` so it applies to the destination page. `context.setExtraHTTPHeaders({ 'User-Agent': '...' })` does **not** override UA on ArkWeb (the header is preserved as browser default).
 - **`locator.hover()` activates CSS `:hover` on typical pages.** The fixture goes through the real `Input.dispatchMouseEvent` path via `page.mouse.move`. On pages where Playwright's `boundingBox()` hangs (e.g. some MutationObserver configurations), it falls back to a JS `mouseover` dispatch after a 5 s timeout — DOM listeners still fire but `:hover` will not activate in that fallback path.
-- **`page.mouse.move()` / `page.mouse.down()` / `page.mouse.up()` work normally.** DOM listeners receive `mousemove` / `mousedown` / `mouseup` / `click` in ArkWeb just as they do on stock Chromium. A narrow edge case (data: URL with embedded newlines AND a shared function reference registered for multiple event types on the same element) was previously documented; reaudit could not reproduce it. The `mouseMove` / `mouseDown` / `mouseUp` fixtures remain available as JS-dispatch fallbacks for unusual cases.
+- **`page.mouse.move()` / `page.mouse.down()` / `page.mouse.up()` work normally.** DOM listeners receive `mousemove` / `mousedown` / `mouseup` / `click` in ArkWeb just as they do on stock Chromium. A previously documented narrow edge case (data: URL with embedded newlines AND a shared function reference registered for multiple event types) could not be reproduced in the v0.3.3 reaudit. The `mouseMove` / `mouseDown` / `mouseUp` fixtures remain in the API surface for backward compatibility but are no longer needed for normal use.
 - **`emulateDevice({ isMobile: true })` does not apply the viewport** — see the note in the `emulateDevice` fixture section above.
 - **`exposeBinding({ handle: true })` is not supported.** Playwright 1.60's public `exposeBinding` signature is `(name, callback)` — the third `{ handle }` argument is silently ignored. The callback receives a serialized form of the argument (DOM nodes arrive as the string `"ref: <Node>"`), not a JSHandle. Use `exposeFunction` or a plain `exposeBinding` callback that reads element properties directly and returns a by-value object.
 - **`process.platform` reads `'linux'`** during the run — Playwright's `calculatePlatform()` only branches on linux/darwin/win32 (falls through to `<unknown>` on openharmony), and 20+ other sites in `playwright-core` read `process.platform` directly (UA string assembly, headful window insets, modifier keys, registry). The adapter patches `process.platform` to `'linux'` and pins `PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-arm64` for `calculatePlatform()`. For real platform checks use `process.env.OHOS_PW_HOST`.
@@ -190,7 +205,7 @@ Playwright's bundled Chromium cannot exec inside the OHOS app sandbox, which bre
 
 **`defineConfig(...)` has no type hints** — set `moduleResolution` to `bundler` or `nodenext` in tsconfig.
 
-**`未发现设备` / 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.
+**`未发现设备` / no device found** — on the device, enable Developer Options → Wireless Debugging and make sure it's on the same Wi-Fi as the host. In CI, run `hdc tconn <ip:port>` manually before tests.
 
 **`Failed to launch` the browser** — bundle not installed or wrong bundle name. List installed browsers with:
 

package/dist/config.mjs

@@ -12,10 +12,22 @@ export function withOpenHarmony(config) {
     // overwritten platform to 'linux' by the time this function runs.
     if (!process.env.OHOS_PW_HOST)
         return config;
+    const multiContextOk = process.env.PW_CHROMIUM_ATTACH_TO_OTHER === '1';
+    const configuredWorkers = typeof config.workers === 'number' ? config.workers : 0;
+    if (multiContextOk && configuredWorkers > 1) {
+        console.warn('[ohos-playwright] workers > 1 with PW_CHROMIUM_ATTACH_TO_OTHER=1: ' +
+            'make sure you import { test } from \'ohos-playwright/parallel\' — ' +
+            'the default fixture shares contexts()[0] across workers and will race. ' +
+            'See README "Multi-worker mode".');
+    }
     return {
         ...config,
-        // Single ArkWeb instance via CDP — workers must be 1.
-        workers: 1,
+        // Without PW_CHROMIUM_ATTACH_TO_OTHER, all workers connect to the same
+        // endpoint and share contexts()[0].pages()[0] — parallel workers would
+        // race on the same page. Force workers:1. With the opt-in env, each
+        // worker can browser.newContext() + ctx.newPage() independently via
+        // ohos-playwright/parallel, so respect the user's workers setting.
+        workers: multiContextOk ? config.workers : 1,
         globalSetup: 'ohos-playwright/setup',
         globalTeardown: 'ohos-playwright/teardown',
         // ArkWeb only speaks Chromium CDP; drop firefox/webkit projects.

package/dist/fixture.d.mts

@@ -1,3 +1,4 @@
+import type { BrowserContext, Page } from '@playwright/test';
 export interface DeviceDescriptor {
     viewport: {
         width: number;
@@ -23,6 +24,10 @@ export interface StorageState {
         }[];
     }[];
 }
+export type PageCleanup = (opts?: {
+    navigateTo?: string;
+}) => Promise<void>;
+export declare function installPageWrappers(page: Page, context: BrowserContext, baseURL: string | undefined): Promise<PageCleanup>;
 export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
     emulateDevice: (descriptor: DeviceDescriptor) => Promise<void>;
     tap: (x: number, y: number) => Promise<void>;

package/dist/fixture.mjs

@@ -16,28 +16,235 @@ function readInfo() {
     return JSON.parse(readFileSync(INFO_PATH, 'utf8'));
 }
 function readEndpoint() { return readInfo().endpoint; }
+export async function installPageWrappers(page, context, baseURL) {
+    const ctxEmit = context.emit.bind(context);
+    // Patch baseURL — save and restore to prevent wrapper accumulation across
+    // tests that share the same page object.
+    const savedGoto = page['goto'];
+    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));
+    }
+    // connectOverCDP reuses an existing tab — Playwright has no record of its
+    // viewport size and viewportSize() returns null. Pre-fetch via CDP.
+    const session = await context.newCDPSession(page);
+    try {
+        try {
+            const { cssVisualViewport } = await session.send('Page.getLayoutMetrics');
+            const cached = {
+                width: Math.round(cssVisualViewport.clientWidth),
+                height: Math.round(cssVisualViewport.clientHeight),
+            };
+            const origViewportSize = page.viewportSize.bind(page);
+            page.viewportSize = () => origViewportSize() ?? cached;
+        }
+        catch {
+            // Non-critical — viewportSize() will still return null if CDP call fails.
+        }
+        // Bring the tab to foreground so Input.dispatchMouseEvent reaches DOM listeners.
+        // page.mouse.move/down/up events are silently dropped when the tab is not active.
+        try {
+            const targets = await session.send('Target.getTargets');
+            const pageTarget = targets.targetInfos.find((t) => t.type === 'page' && t.url === page.url());
+            if (pageTarget) {
+                await session.send('Target.activateTarget', { targetId: pageTarget.targetId });
+            }
+        }
+        catch {
+            // Non-fatal: some ArkWeb versions may not support Target.activateTarget.
+        }
+    }
+    finally {
+        await session.detach();
+    }
+    // Override goBack: Page.navigateToHistoryEntry hangs in ArkWeb (never resolves).
+    // ArkWeb also does not emit Page.frameNavigated for history navigation, so waitForURL
+    // never fires. Poll Page.getNavigationHistory.currentIndex instead.
+    ;
+    page.goBack = async (options) => {
+        const timeout = options?.timeout ?? 30000;
+        const s = await page.context().newCDPSession(page);
+        try {
+            const nav = await s.send('Page.getNavigationHistory');
+            const prevIndex = nav.currentIndex;
+            if (prevIndex <= 0)
+                return null;
+            await page.evaluate(() => history.back());
+            const deadline = Date.now() + timeout;
+            while (Date.now() < deadline) {
+                const nav2 = await s.send('Page.getNavigationHistory');
+                if (nav2.currentIndex < prevIndex)
+                    break;
+                await new Promise(r => setTimeout(r, 80));
+            }
+            if (Date.now() >= deadline)
+                throw new Error(`page.goBack: Timeout ${timeout}ms exceeded`);
+        }
+        finally {
+            await s.detach();
+        }
+        return null;
+    };
+    page.goForward = async (options) => {
+        const timeout = options?.timeout ?? 30000;
+        const s = await page.context().newCDPSession(page);
+        try {
+            const nav = await s.send('Page.getNavigationHistory');
+            const prevIndex = nav.currentIndex;
+            if (prevIndex >= nav.entries.length - 1)
+                return null;
+            await page.evaluate(() => history.forward());
+            const deadline = Date.now() + timeout;
+            while (Date.now() < deadline) {
+                const nav2 = await s.send('Page.getNavigationHistory');
+                if (nav2.currentIndex > prevIndex)
+                    break;
+                await new Promise(r => setTimeout(r, 80));
+            }
+            if (Date.now() >= deadline)
+                throw new Error(`page.goForward: Timeout ${timeout}ms exceeded`);
+        }
+        finally {
+            await s.detach();
+        }
+        return null;
+    };
+    // Override locator().hover() to bypass Playwright's internal visibility check
+    // (which can hang on ArkWeb), but still go through the real Input.dispatchMouseEvent
+    // path so the pointer position is set and CSS :hover activates. The earlier
+    // JS-dispatch workaround was disproved by the 2026-06-27 reaudit — ab-hover-css
+    // shows the native path delivers both DOM events and :hover activation.
+    const savedLocator = page['locator'];
+    const origLocator = page.locator.bind(page);
+    page.locator = (...args) => {
+        const loc = origLocator(...args);
+        loc.hover = async (_options) => {
+            // Try the real Input.dispatchMouseEvent path first (activates :hover).
+            // Some pages (e.g. ones with MutationObservers that re-enter layout) can
+            // make Playwright's evaluate/boundingBox hang on ArkWeb; fall back to a
+            // JS-only dispatch with a tight timeout so hover() at least returns and
+            // DOM listeners fire.
+            const viaRealMouse = await Promise.race([
+                (async () => {
+                    const box = await loc.boundingBox();
+                    if (!box)
+                        return false;
+                    await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+                    return true;
+                })(),
+                new Promise(r => setTimeout(() => r(false), 5000)),
+            ]);
+            if (!viaRealMouse) {
+                await Promise.race([
+                    loc.evaluate((el) => {
+                        el.dispatchEvent(new MouseEvent('mouseover', { bubbles: true, cancelable: true }));
+                    }),
+                    new Promise(r => setTimeout(r, 2000)),
+                ]).catch(() => { });
+            }
+        };
+        return loc;
+    };
+    // ArkWeb's new tab from window.open() is invisible to CDP (Target.createTarget hangs,
+    // Target.targetCreated never fires). Intercept via an init script:
+    //   - queue the URL for our poller
+    //   - return null (Window object hangs CDP serialization if returned)
+    // Guard against multiple addInitScript calls across tests accumulating overrides.
+    const origEvaluate = page.evaluate.bind(page);
+    const alreadyPatched = page['__ohosPopupPatched'];
+    if (!alreadyPatched) {
+        ;
+        page['__ohosPopupPatched'] = true;
+        await page.addInitScript(() => {
+            if (window['__ohosPopupPatched'])
+                return;
+            window['__ohosPopupPatched'] = true;
+            window['__ohosPopupQueue'] = [];
+            window.open = (url) => {
+                ;
+                window['__ohosPopupQueue'].push({ url: String(url ?? '') });
+                return null; // Window object hangs CDP serialization — return null instead
+            };
+        });
+    }
+    const popupPoller = setInterval(async () => {
+        try {
+            const pending = await origEvaluate(() => {
+                const q = window['__ohosPopupQueue'];
+                window['__ohosPopupQueue'] = [];
+                return q;
+            });
+            for (const { url } of pending ?? []) {
+                // context.newPage() calls Target.createTarget which hangs in ArkWeb.
+                // Emit a minimal stub — satisfies waitForLoadState / url / close.
+                const stub = {
+                    waitForLoadState: async () => { },
+                    url: () => url,
+                    close: async () => { },
+                };
+                ctxEmit('page', stub);
+            }
+        }
+        catch { }
+    }, 150);
+    // evaluate() exceptions reject the promise but never become pageerror events
+    // (CDP catches them before they become uncaught). Intercept and re-emit.
+    // Save and restore to prevent wrapper accumulation across tests on the same page object.
+    const savedEvaluate = page['evaluate'];
+    page.evaluate = async (fn, arg) => {
+        try {
+            return await origEvaluate(fn, arg);
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            page.emit('pageerror', err);
+        }
+    };
+    return async (opts) => {
+        clearInterval(popupPoller);
+        page.evaluate = savedEvaluate;
+        page.locator = savedLocator;
+        if (opts?.navigateTo) {
+            // Reset the shared tab before restoring goto — keeps the connection alive.
+            // page.close() would terminate the ArkWeb DevTools socket.
+            try {
+                await page.goto(opts.navigateTo);
+            }
+            catch { }
+        }
+        ;
+        page.goto = savedGoto;
+    };
+}
 export const test = base.extend({
     browser: [
         async ({}, use) => {
             const browser = await chromium.connectOverCDP(readEndpoint());
-            // ArkWeb CDP does not implement Target.createBrowserContext — connectOverCDP
-            // reuses the single existing context. browser.newContext() returns without
-            // throwing but produces an empty shell (0 pages) that silently fails every
-            // subsequent operation. Intercept and throw an explicit, actionable error
-            // so users aren't misled by the false-positive success.
-            const origNewContext = browser.newContext.bind(browser);
-            browser.newContext = (() => {
-                throw new Error('browser.newContext() is not supported in ArkWeb CDP mode (single context only). ' +
-                    'Tests share one context and one page — isolate with localStorage.clear() + page.reload(). ' +
-                    'See ohos-playwright README "Limitations" section.');
-            });
-            try {
-                await use(browser);
+            // ArkWeb's Target.createTarget returns type='other', so Playwright's
+            // crBrowser._onAttachedToTarget skips it and ctx.newPage() throws
+            // "Cannot read properties of undefined (reading '_page')". The upstream
+            // PW_CHROMIUM_ATTACH_TO_OTHER=1 escape hatch fixes newContext/newPage
+            // but also makes Playwright treat internal "other" targets as pages
+            // (perturbs touchscreen / recordHar). When the user has not opted in,
+            // intercept browser.newContext() with a friendly, actionable error.
+            if (!process.env.PW_CHROMIUM_ATTACH_TO_OTHER) {
+                const origNewContext = browser.newContext.bind(browser);
+                browser.newContext = (() => {
+                    throw new Error('browser.newContext() is not supported on ArkWeb unless you opt in via ' +
+                        'process.env.PW_CHROMIUM_ATTACH_TO_OTHER=\'1\' before importing @playwright/test. ' +
+                        'See ohos-playwright README "Limitations" → "Multi-context" for trade-offs.');
+                });
+                try {
+                    await use(browser);
+                }
+                finally {
+                    ;
+                    browser.newContext = origNewContext;
+                }
             }
-            finally {
-                // Restore in case the browser object is reused across workers.
-                ;
-                browser.newContext = origNewContext;
+            else {
+                await use(browser);
             }
         },
         { scope: 'worker' },
@@ -66,210 +273,12 @@ export const test = base.extend({
         const page = info.openedNewTab
             ? ([...pages].reverse().find((p) => p.url() === (info.launchUrl ?? 'about:blank')) ?? pages[pages.length - 1])
             : (pages.find((p) => p.url().startsWith('http://localhost')) ?? pages[0]);
-        const ctxEmit = context.emit.bind(context);
-        // Patch baseURL — save and restore to prevent wrapper accumulation across
-        // tests that share the same page object.
-        const savedGoto = page['goto'];
-        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));
-        }
-        // connectOverCDP reuses an existing tab — Playwright has no record of its
-        // viewport size and viewportSize() returns null. Pre-fetch via CDP.
-        const session = await context.newCDPSession(page);
-        try {
-            try {
-                const { cssVisualViewport } = await session.send('Page.getLayoutMetrics');
-                const cached = {
-                    width: Math.round(cssVisualViewport.clientWidth),
-                    height: Math.round(cssVisualViewport.clientHeight),
-                };
-                const origViewportSize = page.viewportSize.bind(page);
-                page.viewportSize = () => origViewportSize() ?? cached;
-            }
-            catch {
-                // Non-critical — viewportSize() will still return null if CDP call fails.
-            }
-            // Bring the tab to foreground so Input.dispatchMouseEvent reaches DOM listeners.
-            // page.mouse.move/down/up events are silently dropped when the tab is not active.
-            try {
-                const targets = await session.send('Target.getTargets');
-                const pageTarget = targets.targetInfos.find((t) => t.type === 'page' && t.url === page.url());
-                if (pageTarget) {
-                    await session.send('Target.activateTarget', { targetId: pageTarget.targetId });
-                }
-            }
-            catch {
-                // Non-fatal: some ArkWeb versions may not support Target.activateTarget.
-            }
-        }
-        finally {
-            await session.detach();
-        }
-        // Override goBack: Page.navigateToHistoryEntry hangs in ArkWeb (never resolves).
-        // ArkWeb also does not emit Page.frameNavigated for history navigation, so waitForURL
-        // never fires. Poll Page.getNavigationHistory.currentIndex instead.
-        ;
-        page.goBack = async (options) => {
-            const timeout = options?.timeout ?? 30000;
-            const s = await page.context().newCDPSession(page);
-            try {
-                const nav = await s.send('Page.getNavigationHistory');
-                const prevIndex = nav.currentIndex;
-                if (prevIndex <= 0)
-                    return null;
-                await page.evaluate(() => history.back());
-                const deadline = Date.now() + timeout;
-                while (Date.now() < deadline) {
-                    const nav2 = await s.send('Page.getNavigationHistory');
-                    if (nav2.currentIndex < prevIndex)
-                        break;
-                    await new Promise(r => setTimeout(r, 80));
-                }
-                if (Date.now() >= deadline)
-                    throw new Error(`page.goBack: Timeout ${timeout}ms exceeded`);
-            }
-            finally {
-                await s.detach();
-            }
-            return null;
-        };
-        page.goForward = async (options) => {
-            const timeout = options?.timeout ?? 30000;
-            const s = await page.context().newCDPSession(page);
-            try {
-                const nav = await s.send('Page.getNavigationHistory');
-                const prevIndex = nav.currentIndex;
-                if (prevIndex >= nav.entries.length - 1)
-                    return null;
-                await page.evaluate(() => history.forward());
-                const deadline = Date.now() + timeout;
-                while (Date.now() < deadline) {
-                    const nav2 = await s.send('Page.getNavigationHistory');
-                    if (nav2.currentIndex > prevIndex)
-                        break;
-                    await new Promise(r => setTimeout(r, 80));
-                }
-                if (Date.now() >= deadline)
-                    throw new Error(`page.goForward: Timeout ${timeout}ms exceeded`);
-            }
-            finally {
-                await s.detach();
-            }
-            return null;
-        };
-        // Override locator().hover() to bypass Playwright's internal visibility check
-        // (which can hang on ArkWeb), but still go through the real Input.dispatchMouseEvent
-        // path so the pointer position is set and CSS :hover activates. The earlier
-        // JS-dispatch workaround was disproved by the 2026-06-27 reaudit — ab-hover-css
-        // shows the native path delivers both DOM events and :hover activation.
-        const savedLocator = page['locator'];
-        const origLocator = page.locator.bind(page);
-        page.locator = (...args) => {
-            const loc = origLocator(...args);
-            loc.hover = async (_options) => {
-                // Try the real Input.dispatchMouseEvent path first (activates :hover).
-                // Some pages (e.g. ones with MutationObservers that re-enter layout) can
-                // make Playwright's evaluate/boundingBox hang on ArkWeb; fall back to a
-                // JS-only dispatch with a tight timeout so hover() at least returns and
-                // DOM listeners fire.
-                const viaRealMouse = await Promise.race([
-                    (async () => {
-                        const box = await loc.boundingBox();
-                        if (!box)
-                            return false;
-                        await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
-                        return true;
-                    })(),
-                    new Promise(r => setTimeout(() => r(false), 5000)),
-                ]);
-                if (!viaRealMouse) {
-                    await Promise.race([
-                        loc.evaluate((el) => {
-                            el.dispatchEvent(new MouseEvent('mouseover', { bubbles: true, cancelable: true }));
-                        }),
-                        new Promise(r => setTimeout(r, 2000)),
-                    ]).catch(() => { });
-                }
-            };
-            return loc;
-        };
-        // ArkWeb's new tab from window.open() is invisible to CDP (Target.createTarget hangs,
-        // Target.targetCreated never fires). Intercept via an init script:
-        //   - queue the URL for our poller
-        //   - return null (Window object hangs CDP serialization if returned)
-        // Guard against multiple addInitScript calls across tests accumulating overrides.
-        const origEvaluate = page.evaluate.bind(page);
-        const alreadyPatched = page['__ohosPopupPatched'];
-        if (!alreadyPatched) {
-            ;
-            page['__ohosPopupPatched'] = true;
-            await page.addInitScript(() => {
-                if (window['__ohosPopupPatched'])
-                    return;
-                window['__ohosPopupPatched'] = true;
-                window['__ohosPopupQueue'] = [];
-                window.open = (url) => {
-                    ;
-                    window['__ohosPopupQueue'].push({ url: String(url ?? '') });
-                    return null; // Window object hangs CDP serialization — return null instead
-                };
-            });
-        }
-        const popupPoller = setInterval(async () => {
-            try {
-                const pending = await origEvaluate(() => {
-                    const q = window['__ohosPopupQueue'];
-                    window['__ohosPopupQueue'] = [];
-                    return q;
-                });
-                for (const { url } of pending ?? []) {
-                    // context.newPage() calls Target.createTarget which hangs in ArkWeb.
-                    // Emit a minimal stub — satisfies waitForLoadState / url / close.
-                    const stub = {
-                        waitForLoadState: async () => { },
-                        url: () => url,
-                        close: async () => { },
-                    };
-                    ctxEmit('page', stub);
-                }
-            }
-            catch { }
-        }, 150);
-        // evaluate() exceptions reject the promise but never become pageerror events
-        // (CDP catches them before they become uncaught). Intercept and re-emit.
-        // Save and restore to prevent wrapper accumulation across tests on the same page object.
-        const savedEvaluate = page['evaluate'];
-        page.evaluate = async (fn, arg) => {
-            try {
-                return await origEvaluate(fn, arg);
-            }
-            catch (e) {
-                const err = e instanceof Error ? e : new Error(String(e));
-                page.emit('pageerror', err);
-            }
-        };
+        const cleanup = await installPageWrappers(page, context, testInfo.project.use.baseURL);
         try {
             await use(page);
         }
         finally {
-            clearInterval(popupPoller);
-            page.evaluate = savedEvaluate;
-            page.locator = savedLocator;
-            // Reset the test tab to about:blank so it's clean for the next test.
-            // page.close() sends Target.closeTarget which terminates the ArkWeb
-            // DevTools socket — use goto instead to keep the connection alive.
-            if (info.openedNewTab) {
-                try {
-                    await page.goto('about:blank');
-                }
-                catch { }
-            }
-            // Restore goto to prevent wrapper accumulation across tests.
-            ;
-            page.goto = savedGoto;
+            await cleanup({ navigateTo: info.openedNewTab ? 'about:blank' : undefined });
         }
     },
     emulateDevice: async ({ page }, use) => {

package/dist/loader.d.mts

@@ -1,15 +1,2 @@
-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 {};
+import type { ResolveHookContext, ResolveFnOutput } from 'node:module';
+export declare function resolve(specifier: string, context: ResolveHookContext, nextResolve: (specifier: string, context?: Partial<ResolveHookContext>) => ResolveFnOutput): ResolveFnOutput;

package/dist/loader.mjs

@@ -10,13 +10,12 @@ const FIXTURE_HELPER = /\bfixtures?\.[mc]?[tj]sx?$/;
 const OWN_DIST_URL = pathToFileURL(resolvePath(import.meta.dirname) + '/').href;
 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) {
+export function resolve(specifier, context, nextResolve) {
     if (specifier === TARGET) {
         const parent = context.parentURL ?? '';
         const isFromOwnDist = parent.startsWith(OWN_DIST_URL);
         if (TEST_FILE.test(parent) || (FIXTURE_HELPER.test(parent) && !isFromOwnDist)) {
-            const result = await nextResolve(FIXTURE_URL, context);
-            return { url: result.url };
+            return nextResolve(FIXTURE_URL, context);
         }
         if (parent.startsWith(PACKAGE_ROOT_URL)) {
             return nextResolve(specifier, { ...context, parentURL: PROJECT_ANCHOR });

package/dist/parallel.d.mts

@@ -0,0 +1,17 @@
+import type { BrowserContext, Page } from '@playwright/test';
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    emulateDevice: (descriptor: import("./fixture.mts").DeviceDescriptor) => Promise<void>;
+    tap: (x: number, y: number) => Promise<void>;
+    mouseMove: (x: number, y: number, opts?: {
+        steps?: number;
+    }) => Promise<void>;
+    mouseDown: (x: number, y: number) => Promise<void>;
+    mouseUp: (x: number, y: number) => Promise<void>;
+    saveStorageState: (origin?: string) => Promise<import("./fixture.mts").StorageState>;
+    loadStorageState: (state: import("./fixture.mts").StorageState) => Promise<void>;
+    emulateLocale: (locale: string) => Promise<void>;
+} & {
+    context: BrowserContext;
+    page: Page;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export { expect } from '@playwright/test';

package/dist/parallel.mjs

@@ -0,0 +1,48 @@
+import { test as base, installPageWrappers } from "./fixture.mjs";
+// Parallel-safe test fixture for ohos-playwright.
+//
+// Requirements:
+//   - PW_CHROMIUM_ATTACH_TO_OTHER=1 must be set before importing @playwright/test
+//   - Use withOpenHarmony() in your playwright.config.ts as usual
+//
+// Differences from the default 'ohos-playwright' fixture:
+//   - Each test opens its own ArkWeb context via browser.newContext() (test-scoped).
+//     Cookies and localStorage are fully isolated between tests.
+//   - Each test gets ctx.newPage() and both page and context are closed after the
+//     test. All ArkWeb workarounds (goBack, goForward, popup, hover,
+//     evaluate→pageerror) are applied identically to the default fixture.
+//   - newContext() in ArkWeb costs ~100 ms; concurrent creation is safe.
+//
+// Usage:
+//   import { test, expect } from 'ohos-playwright/parallel'
+export const test = base.extend({
+    context: async ({ browser }, use, testInfo) => {
+        if (!process.env.PW_CHROMIUM_ATTACH_TO_OTHER) {
+            throw new Error('[ohos-playwright/parallel] PW_CHROMIUM_ATTACH_TO_OTHER=\'1\' must be set before ' +
+                'importing @playwright/test when using this fixture. ' +
+                'See ohos-playwright README "Multi-worker mode".');
+        }
+        const baseURL = testInfo.project.use.baseURL;
+        const ctx = await browser.newContext(baseURL ? { baseURL } : {});
+        try {
+            await use(ctx);
+        }
+        finally {
+            await ctx.close().catch(() => { });
+        }
+    },
+    page: async ({ context }, use) => {
+        const page = await context.newPage();
+        // baseURL is set on the context via newContext({ baseURL }), so Playwright
+        // resolves relative URLs natively — pass undefined to skip the goto patch.
+        const cleanup = await installPageWrappers(page, context, undefined);
+        try {
+            await use(page);
+        }
+        finally {
+            await cleanup();
+            await page.close().catch(() => { });
+        }
+    },
+});
+export { expect } from '@playwright/test';

package/dist/register.mjs

@@ -1,4 +1,5 @@
-import { register } from 'node:module';
+import { registerHooks } from 'node:module';
+import { resolve } from './loader.mjs';
 // 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.
@@ -21,5 +22,19 @@ if (process.platform === 'openharmony') {
     // process. Safe because we connect over CDP and never touch Playwright's
     // bundled browser binaries. Clean fix requires upstream openharmony branch.
     Object.defineProperty(process, 'platform', { value: 'linux' });
-    register('./loader.mjs', import.meta.url);
+    // ArkWeb's Target.createTarget returns a target with type='other', not
+    // 'page'. Playwright's crBrowser._onAttachedToTarget (crBrowser.ts:191)
+    // only registers 'page' targets into _crPages — 'other' targets get
+    // detached and ctx.newPage() throws "Cannot read properties of undefined
+    // (reading '_page')".
+    //
+    // PW_CHROMIUM_ATTACH_TO_OTHER (crBrowser.ts:181) is playwright's upstream
+    // escape hatch: treat type='other' as page so newContext/newPage work.
+    // It's opt-in (not set here by default) because it also makes Playwright
+    // treat ArkWeb's internal "other" targets (shared workers, etc.) as pages,
+    // which perturbs page-list assumptions in tests that use touchscreen /
+    // recordHar. Users who need multi-context set it explicitly:
+    //   process.env.PW_CHROMIUM_ATTACH_TO_OTHER = '1'
+    // before importing @playwright/test.
+    registerHooks({ resolve });
 }

package/dist/setup.d.mts

@@ -7,7 +7,6 @@ export declare function retry<T>(fn: () => T | Promise<T>, { max, interval, labe
 export declare function findBrowserPid(): number | null;
 export declare function countCdpPages(listJson: string): number;
 export declare function hasDeviceConnected(): boolean;
-export declare function discoverDevices(): string[];
 export declare function tryLocalDevice(): boolean;
 export declare function ensureHdcKey(): boolean;
 export declare function ensureDeviceConnected(): Promise<void>;

package/dist/setup.mjs

@@ -107,13 +107,34 @@ function pickFreePort() {
         srv.on('error', rej);
     });
 }
+function parseFportRules(lsOutput) {
+    const rules = [];
+    for (const line of lsOutput.split('\n')) {
+        const m = line.match(/tcp:(\d+)\s+(localabstract:\S+)/);
+        if (m)
+            rules.push({ port: m[1], socket: m[2] });
+    }
+    return rules;
+}
 function setupForward(port, socketName) {
-    const ruler = `tcp:${port} localabstract:${socketName}`;
+    // Remove all existing rules for this socket (any port) before creating a new
+    // one — prevents rule accumulation from crashed runs. hdc fport rm requires
+    // separate arguments; a single "tcp:PORT localabstract:SOCKET" string is
+    // silently ignored by hdc.
     try {
-        hdc(['fport', 'rm', ruler]);
+        const ls = hdc(['fport', 'ls']);
+        const target = `localabstract:${socketName}`;
+        for (const { port: p, socket: s } of parseFportRules(ls)) {
+            if (s === target) {
+                try {
+                    hdc(['fport', 'rm', `tcp:${p}`, s]);
+                }
+                catch { }
+            }
+        }
     }
     catch { }
-    hdc(['fport', 'tcp:' + port, 'localabstract:' + socketName]);
+    hdc(['fport', `tcp:${port}`, `localabstract:${socketName}`]);
 }
 function cdpGet(port, path) {
     return new Promise((res) => {
@@ -142,18 +163,6 @@ 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));
-}
 // 已连接时 hdc tconn 返回 "Target is connected, repeat operation"，也视作成功。
 function tconn(addr) {
     try {
@@ -175,7 +184,6 @@ const CONNECT_HELP = [
     '  1) 进入「设置 → 关于本机」连点版本号开启「开发者选项」',
     '  2) 进入「开发者选项」启用「无线调试」',
     '  3) 确认设备与本机在同一 Wi-Fi 下',
-    '  4) 防火墙放行本机 UDP:8710 入站（hdc discover 广播用）',
     '也可手动跑 `hdc tconn <ip:port>` 后重新启动测试。',
     '若不希望自动连接，设 OHOS_PW_AUTO_CONNECT=0 跳过。',
 ].join('\n');
@@ -264,15 +272,6 @@ export async function ensureDeviceConnected() {
         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);

package/dist/teardown.mjs

@@ -10,10 +10,13 @@ export default async function globalTeardown() {
     catch {
         return;
     }
-    const ruler = `tcp:${info.port} localabstract:${info.socket}`;
+    const tcpArg = `tcp:${info.port}`;
+    const sockArg = `localabstract:${info.socket}`;
     try {
-        execFileSync(HDC, ['fport', 'rm', ruler], { stdio: ['ignore', 'pipe', 'pipe'] });
-        console.log(`[ohos-playwright] removed fport ${ruler}`);
+        // hdc fport rm requires separate arguments — a single combined string is
+        // silently ignored.
+        execFileSync(HDC, ['fport', 'rm', tcpArg, sockArg], { stdio: ['ignore', 'pipe', 'pipe'] });
+        console.log(`[ohos-playwright] removed fport ${tcpArg} ${sockArg}`);
     }
     catch (e) {
         const msg = e instanceof Error ? e.message?.split('\n')[0] : String(e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ohos-playwright",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Playwright adapter for OpenHarmony / ArkWeb via hdc + CDP",
   "license": "MIT",
   "author": "social4hyq",
@@ -38,7 +38,8 @@
     "./teardown": "./dist/teardown.mjs",
     "./register": "./dist/register.mjs",
     "./loader": "./dist/loader.mjs",
-    "./config": "./dist/config.mjs"
+    "./config": "./dist/config.mjs",
+    "./parallel": "./dist/parallel.mjs"
   },
   "bin": {
     "ohos-playwright": "./dist/cli.mjs"