ohos-playwright 0.3.5 → 0.5.0

package/README.md

@@ -64,12 +64,16 @@ The following Playwright APIs have been validated on ArkWeb / HarmonyOS 6.1 (Chr
 | Navigation wait | `page.waitForURL()` — string, glob, RegExp, and `history.pushState` client-side navigation |
 | Frames | `page.frames()`, `page.mainFrame()`, `frame.url()` |
 | Viewport | `page.viewportSize()` (pre-fetched via `Page.getLayoutMetrics` for reused CDP tabs), `page.setViewportSize()` (applies precisely) |
-| Media emulation | `page.emulateMedia({ colorScheme })` |
+| Media emulation | `page.emulateMedia({ colorScheme, reducedMotion, forcedColors, media })` — all four options work; combine freely |
+| Visual snapshot | `expect(page).toHaveScreenshot()`, `expect(locator).toHaveScreenshot()` — use `SNAPSHOT_ENGINE=<tag>` to separate baselines when comparing ArkWeb vs another engine (both produce `*-linux.png` filenames) |
+| API request | `request` fixture (`page`-independent HTTP client), `playwright.request.newContext()` — both work |
+| Locator handler | `page.addLocatorHandler()`, `page.removeLocatorHandler()` — auto-dismisses overlays before Playwright's action retry |
+| HTTP credentials | `browser.newContext({ httpCredentials: { username, password } })` — auto-injects Basic Auth. `ctx.newPage()` requires `PW_CHROMIUM_ATTACH_TO_OTHER=1`; cookie/storage operations work without it. **Note:** do not combine with `page.route()` on the same page — both use `Fetch.enable` internally and credentials will not be injected when a route is active. |
 | Web workers | `page.workers()` — returns the list of active workers |
 | 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 **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. |
+| Hover events | `locator.hover()` — fires `mouseover` / `mouseenter` event listeners **and** activates the CSS `:hover` pseudo-class via `boundingBox()` + `page.mouse.move()` (real `Input.dispatchMouseEvent` path) |
 | Locale (partial) | `emulateLocale(tag)` fixture — rewrites `navigator.language` / `navigator.languages` via `addInitScript`; does not affect HTTP `Accept-Language` or browser UI locale |
 | 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 |
@@ -77,7 +81,7 @@ The following Playwright APIs have been validated on ArkWeb / HarmonyOS 6.1 (Chr
 
 ### `emulateDevice` fixture
 
-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.
+Because `ctx.newPage()` requires `PW_CHROMIUM_ATTACH_TO_OTHER=1` (see "Multi-context" in Limitations), device emulation is exposed as a Playwright fixture parameter backed by CDP `Emulation.*` commands.
 
 ```ts
 import { test, expect } from '@playwright/test'
@@ -121,7 +125,9 @@ Coordinates are CSS pixels relative to the viewport (same as `touchscreen.tap`).
 ## Limitations
 
 - **Chromium only.** firefox and webkit aren't available on HarmonyOS.
-- **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 })`.
+- **`browser.newContext()` works; `ctx.newPage()` requires opt-in.** `browser.newContext()` is available without any opt-in — use it freely for `addCookies` / `storageState()` / `clearCookies()`. However, `ctx.newPage()` on ArkWeb throws Playwright's natural `Cannot read properties of undefined (reading '_page')` because ArkWeb's `Target.createTarget` returns `type: 'other'` (not `'page'`), causing Playwright's `crBrowser._onAttachedToTarget` to skip the new target. To opt in to full `ctx.newPage()` support, set `process.env.PW_CHROMIUM_ATTACH_TO_OTHER = '1'` **before** importing `@playwright/test` — Playwright's upstream escape hatch then treats `'other'` targets as pages. 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 })`.
+
+  > **v0.5.0 breaking change:** Previously `browser.newContext()` threw a friendly error when `PW_CHROMIUM_ATTACH_TO_OTHER` was unset. Now it succeeds for cookie/storage operations; `ctx.newPage()` will throw Playwright's natural `_page undefined` error instead.
 
   **Multi-worker mode.** To run tests in parallel across multiple workers, two things are required together:
 
@@ -132,15 +138,16 @@ Coordinates are CSS pixels relative to the viewport (same as `touchscreen.tap`).
   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.
+  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 propagation) 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 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.
+- **`locator.hover()` activates CSS `:hover`.** The override calls `boundingBox()` + `page.mouse.move()` (real `Input.dispatchMouseEvent` path). `page.mouse.move()` / `page.mouse.down()` / `page.mouse.up()` deliver DOM events on ArkWeb identically to stock Chromium.
 - **`emulateDevice({ isMobile: true })` does not apply the viewport** — see the note in the `emulateDevice` fixture section above.
+- **`context.recordVideo` is not supported.** ArkWeb does not implement `Page.startScreencast` (the CDP command Playwright uses for video recording). When running against a remote Chromium via `OHOS_PW_CDP_URL`, Playwright's ffmpeg binary also cannot execute on HarmonyOS without signing. Use `page.screenshot()` for visual verification instead.
+- **`launchOptions.proxy` is not applicable** in `connectOverCDP` mode — there is no launch phase where proxy settings can be injected. Use `page.route()` to intercept and rewrite requests at the Playwright layer.
 - **`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`.
 
@@ -219,7 +226,7 @@ Then set `OHOS_PW_BUNDLE` (e.g. `OHOS_PW_BUNDLE=com.quark.ohosbrowser`).
 
 **`CDP probe failed`** — leftover `hdc` forward rule from a prior crashed run. `hdc fport ls` to inspect, `hdc fport rm tcp:<port> localabstract:<socket>` to clear.
 
-**`page.goto('/foo')` doesn't prepend baseURL** — Playwright's standard behavior is `/foo` → `http://localhost:5173/foo`. If it's not working, check `use.baseURL` in `playwright.config.ts`.
+**`page.goto('/foo')` doesn't prepend baseURL** — Playwright's standard behavior is `/foo` → `http://localhost:5173/foo`. The adapter injects `baseURL` directly into the context's internal options so Playwright's own URL resolution applies. If it's not working, verify `use.baseURL` is set in `playwright.config.ts` and that `withOpenHarmony()` wraps the config.
 
 ## License
 

package/dist/fixture.d.mts

@@ -31,11 +31,6 @@ export declare function installPageWrappers(page: Page, context: BrowserContext,
 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>;
-    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<StorageState>;
     loadStorageState: (state: StorageState) => Promise<void>;
     emulateLocale: (locale: string) => Promise<void>;

package/dist/fixture.mjs

@@ -18,14 +18,6 @@ function readInfo() {
 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);
@@ -42,18 +34,6 @@ export async function installPageWrappers(page, context, baseURL) {
         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();
@@ -110,39 +90,19 @@ export async function installPageWrappers(page, context, baseURL) {
         }
         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.
+    // Override locator().hover() to use page.mouse.move() directly so CSS :hover
+    // activates. Playwright's built-in hover() goes through a visibility check path
+    // that can hang on ArkWeb; bypassing it is safe because mouse.move() has been
+    // verified to deliver both DOM events and :hover activation (ab-hover-css probe).
     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(() => { });
-            }
+            const box = await loc.boundingBox();
+            if (!box)
+                return;
+            await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
         };
         return loc;
     };
@@ -206,46 +166,24 @@ export async function installPageWrappers(page, context, baseURL) {
         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.
+            // Reset the shared tab to a neutral state — page.close() would terminate
+            // the ArkWeb DevTools socket so we navigate instead.
             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'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;
-                }
-            }
-            else {
-                await use(browser);
-            }
+            // browser.newContext() + addCookies / storageState() work in connectOverCDP mode.
+            // ctx.newPage() requires PW_CHROMIUM_ATTACH_TO_OTHER=1 on ArkWeb (Target.createTarget
+            // returns type='other' so Playwright skips the new target); without it Playwright
+            // throws its natural "_page undefined" error.
+            await use(browser);
         },
         { scope: 'worker' },
     ],
@@ -342,45 +280,6 @@ export const test = base.extend({
             }
         });
     },
-    mouseMove: async ({ page }, use) => {
-        // ArkWeb CDP limitation: events dispatched via locator.evaluate() only reach
-        // page-script listeners if the listener body contains no closure references and
-        // the element has only a single addEventListener call. Any script complexity
-        // (outer variable declarations, multiple listeners) causes ArkWeb to route the
-        // callback into an isolated CDP execution context where closures are inaccessible,
-        // silently suppressing the event. For typical web applications this fixture
-        // will not deliver events. Prefer locator.click() / locator.fill() where possible.
-        await use(async (x, y, opts) => {
-            const steps = Math.max(1, opts?.steps ?? 1);
-            for (let i = 0; i < steps; i++) {
-                await page.locator(':root').evaluate((root, [x, y]) => {
-                    const el = root.ownerDocument.elementFromPoint(x, y);
-                    if (el)
-                        el.dispatchEvent(new MouseEvent('mousemove', { bubbles: true, cancelable: true, clientX: x, clientY: y }));
-                }, [x, y]);
-            }
-        });
-    },
-    mouseDown: async ({ page }, use) => {
-        await use(async (x, y) => {
-            await page.locator(':root').evaluate((root, [x, y]) => {
-                const el = root.ownerDocument.elementFromPoint(x, y);
-                if (el)
-                    el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, cancelable: true, clientX: x, clientY: y, button: 0, buttons: 1 }));
-            }, [x, y]);
-        });
-    },
-    mouseUp: async ({ page }, use) => {
-        await use(async (x, y) => {
-            await page.locator(':root').evaluate((root, [x, y]) => {
-                const el = root.ownerDocument.elementFromPoint(x, y);
-                if (el) {
-                    el.dispatchEvent(new MouseEvent('mouseup', { bubbles: true, cancelable: true, clientX: x, clientY: y, button: 0 }));
-                    el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, clientX: x, clientY: y, button: 0 }));
-                }
-            }, [x, y]);
-        });
-    },
     saveStorageState: async ({ page, context }, use) => {
         await use(async (origin) => {
             const derivedOrigin = origin ?? new URL(page.url()).origin;

package/dist/parallel.d.mts

@@ -2,11 +2,6 @@ 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>;

package/package.json

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