ohos-playwright 0.2.10 → 0.2.11

package/README.md

@@ -38,16 +38,22 @@ The following Playwright APIs have been validated on ArkWeb / HarmonyOS 6.1 (Chr
 | Category | APIs |
 |---|---|
 | Network interception | `page.route()`, `route.fulfill()`, `route.abort()`, `page.unroute()` |
+| Network headers | `page.setExtraHTTPHeaders()` — custom headers reach the server |
+| Network conditions | `context.setOffline(true / false)` — actually applies (`ERR_INTERNET_DISCONNECTED` ↔ reachable) |
 | Screenshot | `page.screenshot({ type: 'jpeg' \| 'png' })`, `locator.screenshot()` |
+| PDF | `page.pdf()` — Chromium-only API, implemented by ArkWeb (produces a valid `%PDF` document) |
+| Tracing | `context.tracing.start()` / `stop({ path })` — works under `connectOverCDP`; the resulting zip contains trace + screenshots + source maps |
 | Geolocation | `context.setGeolocation()`, `context.grantPermissions(['geolocation'])` |
-| Device emulation | `emulateDevice` fixture (see below) |
-| Input | `locator.fill()`, `locator.type()`, `keyboard.press()` |
+| Device emulation | `emulateDevice` fixture (see below — `isMobile: false` for a precise viewport) |
+| Input | `locator.fill()`, `locator.type()`, `keyboard.press()`, `page.selectOption()` |
+| Drag & drop | `locator.dragTo()` — triggers a `drop` event |
+| File upload | `page.setInputFiles()` — fires `change`, file content readable |
 | Cookies | `context.addCookies()`, `context.cookies()`, `context.clearCookies()` |
 | Dialog | `page.on('dialog')`, `dialog.accept()`, `dialog.dismiss()`, `dialog.message()`, `dialog.type()` |
 | Popup | `context.waitForEvent('page')` + `window.open()` — stub Page with `url()`, `waitForLoadState()`, `close()` |
 | Page events | `page.on('pageerror')`, `page.on('console')`, `page.on('download')` |
 | Frames | `page.frames()`, `page.mainFrame()`, `frame.url()` |
-| Viewport | `page.viewportSize()` (pre-fetched via `Page.getLayoutMetrics` for reused CDP tabs) |
+| Viewport | `page.viewportSize()` (pre-fetched via `Page.getLayoutMetrics` for reused CDP tabs), `page.setViewportSize()` (applies precisely) |
 | Media emulation | `page.emulateMedia({ colorScheme })` |
 
 ### `emulateDevice` fixture
@@ -58,12 +64,12 @@ Because `newContext()` is not supported in connectOverCDP mode, device emulation
 import { test, expect } from '@playwright/test'
 import type { DeviceDescriptor } from 'ohos-playwright/fixture'
 
-test('mobile viewport', async ({ page, emulateDevice }) => {
+test('precise viewport', async ({ page, emulateDevice }) => {
+  // isMobile: false applies the viewport precisely (window.innerWidth === 375).
   await emulateDevice({
     viewport: { width: 375, height: 812 },
     deviceScaleFactor: 3,
-    isMobile: true,
-    userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) ...',
+    isMobile: false,
   })
   expect(await page.evaluate(() => window.innerWidth)).toBe(375)
 })
@@ -71,10 +77,38 @@ test('mobile viewport', async ({ page, emulateDevice }) => {
 
 `emulateDevice` settings persist for the lifetime of the page. Call it again with `{ viewport: { width: 1280, height: 720 }, isMobile: false }` to restore defaults.
 
+> **⚠️ `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. Note that `userAgent` is also not applied (`Emulation.setUserAgentOverride` is acked but ignored by ArkWeb); the browser UA cannot be changed via CDP.
+
+### `tap` fixture
+
+ArkWeb fully implements touch input via CDP `Input.dispatchTouchEvent`, but Playwright's `page.touchscreen.tap()` refuses to run unless the context was created with `hasTouch: true` — impossible in single-context reuse mode. The `tap` fixture exposes a CDP-backed tap that works regardless:
+
+```ts
+import { test, expect } from '@playwright/test'
+
+test('tap a button', async ({ page, tap }) => {
+  await page.goto('http://localhost:5173/')
+  const box = await page.locator('#submit').boundingBox()
+  await tap(box.x + box.width / 2, box.y + box.height / 2)
+  await expect(page.locator('#result')).toHaveText('Done')
+})
+```
+
+Coordinates are CSS pixels relative to the viewport (same as `touchscreen.tap`). Each call issues a `touchStart` + `touchEnd` pair, which also synthesises a `click` event on the targeted element — so it works for both touch handlers and click handlers.
+
 ## Limitations
 
 - **Chromium only.** firefox and webkit aren't available on HarmonyOS.
-- **One context, one page.** `newContext()` / `newPage()` aren't supported. Isolate tests with `localStorage.clear()` + `page.reload()`. For device emulation use the `emulateDevice` fixture instead of `browser.newContext({ ...device })`.
+- **One context, one page.** `newContext()` / `newPage()` aren't supported (both throw an explicit error). Isolate tests with `localStorage.clear()` + `page.reload()`. For device emulation use the `emulateDevice` fixture instead of `browser.newContext({ ...device })`.
+- **`locator.hover()` hangs** on ArkWeb (CDP `Input.dispatchMouseEvent` mouseMoved blocks until the Playwright timeout). Use `:focus`-driven styles or a direct `click()` instead of hover-driven assertions.
+- **`page.goBack()` / `page.goForward()` hang** (CDP history navigation never resolves). Re-navigate with `page.goto()` instead.
+- **`Emulation.setUserAgentOverride` is ignored** — the command is acked but `navigator.userAgent` is unchanged. The browser UA cannot be changed via CDP.
+- **`mouse.wheel()` is a no-op** — the command succeeds but `scrollTop` stays 0. Scroll via `page.evaluate(() => el.scrollTo(...))`.
+- **Service Workers unavailable** — `navigator.serviceWorker` is `undefined` on ArkWeb; PWA / SW-based tests are not possible.
+- **`page.workers()` returns empty** for web workers — CDP does not auto-attach worker targets. The workers themselves run fine (messages reach the main page), only the listing is affected.
+- **Clipboard is a false positive** — `navigator.clipboard.writeText/readText` do not throw but `readText` returns `undefined`. Don't assert on clipboard contents.
+- **`emulateDevice({ isMobile: true })` does not apply the viewport** — see the note in the `emulateDevice` fixture section above.
 - **`process.platform` reads `'linux'`** during the run — we patch it because Playwright's hostPlatform detection only branches on linux/darwin/win32 and falls through to `<unknown>` on openharmony. For real platform checks use `process.env.OHOS_PW_HOST`.
 
 ## Environment variables

package/dist/fixture.d.mts

@@ -7,7 +7,26 @@ export interface DeviceDescriptor {
     isMobile?: boolean;
     userAgent?: string;
 }
+export interface StorageState {
+    cookies: {
+        name: string;
+        value: string;
+        domain?: string;
+        path?: string;
+        url?: string;
+    }[];
+    origins: {
+        origin: string;
+        localStorage: {
+            name: string;
+            value: string;
+        }[];
+    }[];
+}
 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>;
+    saveStorageState: (origin?: string) => Promise<StorageState>;
+    loadStorageState: (state: StorageState) => Promise<void>;
 }, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
 export { expect } from '@playwright/test';

package/dist/fixture.mjs

@@ -8,7 +8,25 @@ export const test = base.extend({
     browser: [
         async ({}, use) => {
             const browser = await chromium.connectOverCDP(readEndpoint());
-            await use(browser);
+            // 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);
+            }
+            finally {
+                // Restore in case the browser object is reused across workers.
+                ;
+                browser.newContext = origNewContext;
+            }
         },
         { scope: 'worker' },
     ],
@@ -122,6 +140,16 @@ export const test = base.extend({
         await use(async (descriptor) => {
             const session = await page.context().newCDPSession(page);
             try {
+                // ArkWeb note: with mobile:true, Emulation.setDeviceMetricsOverride enables
+                // the mobile layout-viewport path and the passed width/height are ignored
+                // (window.innerWidth reads 980 regardless). Use isMobile:false for a
+                // precise viewport. See README "emulateDevice fixture" section.
+                if (descriptor.isMobile) {
+                    console.warn('[ohos-playwright] emulateDevice({ isMobile: true }): ArkWeb renders at the 980px ' +
+                        'default mobile layout viewport; the passed width/height will NOT apply. ' +
+                        'Use isMobile: false for a precise viewport.');
+                }
+                // ArkWeb note: setUserAgentOverride is acked but ignored — UA cannot be changed via CDP.
                 await session.send('Emulation.setDeviceMetricsOverride', {
                     width: descriptor.viewport.width,
                     height: descriptor.viewport.height,
@@ -139,5 +167,84 @@ export const test = base.extend({
             }
         });
     },
+    tap: async ({ page }, use) => {
+        await use(async (x, y) => {
+            const session = await page.context().newCDPSession(page);
+            try {
+                // ArkWeb fully implements Input.dispatchTouchEvent (verified: touchstart
+                // touches=1 | touchend received). Playwright's touchscreen.tap() requires
+                // hasTouch at context creation, which is impossible in single-context reuse
+                // mode. This wrapper issues a press+release pair directly.
+                // TouchPoint.state isn't in Playwright's TS types but is part of the CDP
+                // spec and accepted by ArkWeb; cast to any to bypass the narrowed type.
+                await session.send('Input.dispatchTouchEvent', {
+                    type: 'touchStart',
+                    touchPoints: [{ x, y, id: 0, state: 'pressed' }],
+                    modifiers: 0,
+                    timeStamp: 0,
+                });
+                await session.send('Input.dispatchTouchEvent', {
+                    type: 'touchEnd',
+                    touchPoints: [{ x, y, id: 0, state: 'released' }],
+                    modifiers: 0,
+                    timeStamp: 0,
+                });
+            }
+            finally {
+                await session.detach();
+            }
+        });
+    },
+    saveStorageState: async ({ page, context }, use) => {
+        await use(async (origin) => {
+            const derivedOrigin = origin ?? new URL(page.url()).origin;
+            // Cookies come from the context (works in reuse mode). Filter to the
+            // target origin so we don't serialise unrelated domains that happen to
+            // share the single ArkWeb context. Match by hostname (cookies store
+            // domain without port; e.g. cookie.domain='127.0.0.1' for host 127.0.0.1:port).
+            const hostname = new URL(derivedOrigin).hostname;
+            const allCookies = await context.cookies();
+            const cookies = allCookies
+                .filter((c) => {
+                if (!origin)
+                    return true;
+                const d = c.domain ?? '';
+                // cookie domain may have leading '.' (host-only=false) — strip it.
+                const bare = d.startsWith('.') ? d.slice(1) : d;
+                return bare === hostname || hostname.endsWith(bare);
+            })
+                .map((c) => ({ name: c.name, value: c.value, domain: c.domain, path: c.path }));
+            // localStorage must be read in a same-origin document; navigate if needed.
+            const cur = page.url();
+            if (!cur.startsWith(derivedOrigin))
+                await page.goto(derivedOrigin + '/');
+            const localStorage = await page.evaluate(() => {
+                const items = [];
+                for (let i = 0; i < window.localStorage.length; i++) {
+                    const name = window.localStorage.key(i);
+                    items.push({ name, value: window.localStorage.getItem(name) });
+                }
+                return items;
+            });
+            return { cookies, origins: [{ origin: derivedOrigin, localStorage }] };
+        });
+    },
+    loadStorageState: async ({ page, context }, use) => {
+        await use(async (state) => {
+            if (state.cookies?.length)
+                await context.addCookies(state.cookies);
+            for (const o of state.origins ?? []) {
+                if (!o.localStorage?.length)
+                    continue;
+                // localStorage writes must run in a same-origin document.
+                if (!page.url().startsWith(o.origin))
+                    await page.goto(o.origin + '/');
+                await page.evaluate((items) => {
+                    for (const { name, value } of items)
+                        window.localStorage.setItem(name, value);
+                }, o.localStorage);
+            }
+        });
+    },
 });
 export { expect } from '@playwright/test';

package/package.json

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