@testivai/witness-webdriverio 0.4.5 → 0.5.0

package/README.md

@@ -131,6 +131,11 @@ Captures a viewport screenshot, the DOM and the element map, and writes them as
 | `options.maxElements` | number | Cap on elements collected for the element map. Default: 3000. |
 | `options.ignoreSelectors` | string[] | Elements hidden (`visibility: hidden`) for this capture; merged with the global `ignoreSelectors` from `.testivai/config.json`. |
 | `options.stabilize` | boolean | Override capture stabilization (animations frozen, caret hidden, fonts awaited). Default: `true` (or the global `stabilize` setting). |
+| `options.native` | boolean | Native app mode (experimental): detected by default in an Appium session on a native Android or iOS screen. `true` forces it, `false` keeps the web path. |
+| `options.maskStatusBar` | boolean | Native mode only: mask the status bar, measured at capture time (Android: the window manager's bar, `mobile: getSystemBars`; iOS: `mobile: viewportRect`). Default: `true`. |
+| `options.context` | string | Capture in another Appium context for this call, then switch back: `'webview'` (the app's web view) or an exact context name. For a hybrid app driven in the native context, the web view is captured as a page, with every layer. |
+
+In an Appium session on a native app screen, `witness()` runs no page script (a native screen has no DOM): it takes the whole screen, masks the status bar, records the device, and keys the snapshot `<name>__<platform>-<device>-<osMajor>`. Pixel diff only. See [Native mobile apps](https://github.com/testivai/testivai-oss/blob/main/docs/guides/native-mobile.md).
 
 ### `TestivaiService`
 
@@ -147,6 +152,7 @@ Class registered as a WDIO service. Implements `onComplete`.
 ## Status
 
 - **Local mode**: stable
+- **Native app mode**: experimental (verified on an Android 14 emulator; iOS not verified)
 
 ## Links
 

package/dist/element-map.d.ts

@@ -14,7 +14,7 @@ export interface PageElementMap {
  * run (so all lanes produce identical maps), plus the viewport it was taken
  * in. WebdriverIO string scripts need an explicit `return`.
  */
-export declare function elementMapScript(maxElements: number, ignoreSelectors: string[]): string;
+export declare function elementMapScript(maxElements: number, ignoreSelectors: string[], idAttributes?: string[]): string;
 export declare function isPageElementMap(value: unknown): value is PageElementMap;
 /**
  * WebDriver's Take Screenshot captures the viewport, while the collector

package/dist/element-map.js

@@ -9,8 +9,8 @@ const witness_1 = require("@testivai/witness");
  * run (so all lanes produce identical maps), plus the viewport it was taken
  * in. WebdriverIO string scripts need an explicit `return`.
  */
-function elementMapScript(maxElements, ignoreSelectors) {
-    return (`return { elements: ${(0, witness_1.buildElementMapExpression)(maxElements, ignoreSelectors)}, ` +
+function elementMapScript(maxElements, ignoreSelectors, idAttributes = []) {
+    return (`return { elements: ${(0, witness_1.buildElementMapExpression)(maxElements, ignoreSelectors, idAttributes)}, ` +
         'scrollX: window.scrollX || 0, scrollY: window.scrollY || 0, ' +
         'viewportWidth: window.innerWidth, viewportHeight: window.innerHeight, ' +
         'dpr: window.devicePixelRatio || 1 };');

package/dist/types.d.ts

@@ -18,6 +18,22 @@ export interface WitnessBrowser {
      * Type kept loose to accept WDIO 8/9 signature variants.
      */
     execute<T = unknown>(script: string | ((...args: any[]) => T), ...args: any[]): Promise<T>;
+    /**
+     * The session's W3C capabilities (WebdriverIO's `browser.capabilities`).
+     * Optional: when present, the browser, its version and the driver are
+     * recorded as capture provenance in the capture's metadata.json.
+     */
+    capabilities?: Record<string, unknown>;
+    /**
+     * Appium's current context (`NATIVE_APP`, `WEBVIEW_…`): WebdriverIO's
+     * `browser.getContext()`. Asked only in a mobile session that names no
+     * browser, to tell a native screen from a hybrid app's web view.
+     */
+    getContext?(): Promise<unknown>;
+    /** Appium's contexts (WebdriverIO's `browser.getContexts()`), for `options.context`. */
+    getContexts?(): Promise<unknown[]>;
+    /** Switch Appium's context (WebdriverIO's `browser.switchContext()`), for `options.context`. */
+    switchContext?(context: string): Promise<unknown>;
 }
 /**
  * Options for a single witness() call. All optional.
@@ -58,6 +74,32 @@ export interface WitnessOptions {
      * via `stabilize` in `.testivai/config.json`; this per-call value wins).
      */
     stabilize?: boolean;
+    /**
+     * Native app mode (experimental). By default it is detected: an Appium
+     * session on Android or iOS that names no browser, in the `NATIVE_APP`
+     * context (or, when the context cannot be read, started with `app`,
+     * `appPackage` or `bundleId`). A native screen has no page, so no page
+     * script runs: the capture is the screenshot alone (pixel diff only), the
+     * status bar is masked, the environment comes from the capabilities, and
+     * the snapshot is keyed by device. `true` forces it, `false` turns it off.
+     */
+    native?: boolean;
+    /**
+     * Native mode only: mask the status bar, measured at capture time: on
+     * Android the bar's frame in the window manager (`mobile: getSystemBars`),
+     * on iOS `mobile: viewportRect`. Default: true.
+     */
+    maskStatusBar?: boolean;
+    /**
+     * Capture in another Appium context for this call, then switch back (also
+     * when the capture fails). `'webview'` is the app's web view: the one
+     * named after the app's package, else the first `WEBVIEW_…` context. Any
+     * other value is an exact context name (`'WEBVIEW_com.example.app'`,
+     * `'NATIVE_APP'`). For a hybrid app driven in the native context, this
+     * captures its web view as a page, with every layer. Needs WebView
+     * debugging enabled in the app's build.
+     */
+    context?: 'webview' | (string & {});
 }
 /**
  * Configuration passed to the WDIO service.

package/dist/witness.js

@@ -57,6 +57,8 @@ exports.witness = witness;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const witness_1 = require("@testivai/witness");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const ADAPTER_VERSION = require('../package.json').version;
 const element_map_1 = require("./element-map");
 /** id of the style element injected for the duration of a capture */
 const STYLE_ID = '__testivai_capture_css__';
@@ -116,6 +118,99 @@ async function waitForFonts(browser) {
         await new Promise((resolve) => setTimeout(resolve, 100));
     }
 }
+/** A variant as it goes into a snapshot name. */
+const variantSegment = (variant) => variant.replace(/[^a-z0-9_-]+/gi, '_').toLowerCase();
+/**
+ * Whether this capture is of a native app screen (experimental native mode).
+ * Only a mobile session that names no browser is asked for its context, so a
+ * browser session makes no extra call. NATIVE_APP is native; a web view
+ * (WEBVIEW_…, CHROMIUM) is a page. When the context cannot be read, the
+ * capabilities decide: started on an app (app, appPackage, bundleId).
+ */
+async function isNativeCapture(browser, forced) {
+    if (forced !== undefined)
+        return forced;
+    const caps = browser.capabilities;
+    if (!(0, witness_1.mobilePlatform)(caps) || (0, witness_1.namesBrowser)(caps))
+        return false;
+    if (typeof browser.getContext === 'function') {
+        try {
+            const context = await browser.getContext();
+            const id = typeof context === 'string' ? context : context?.id;
+            if (typeof id === 'string' && id.length > 0)
+                return id === 'NATIVE_APP';
+        }
+        catch {
+            // the capabilities decide
+        }
+    }
+    return (0, witness_1.isNativeAppCapabilities)(caps);
+}
+/**
+ * Native mode: a native screen has no page, so no page script runs (Appium
+ * rejects them all there, and WebdriverIO resends each failed one three
+ * times: ~1.5 s each, measured on an Android 14 emulator). The capture is the
+ * screenshot alone, with the status bar masked (`statusBarHeight`), the
+ * environment from the capabilities, and the name keyed by device unless the
+ * call gives a variant.
+ */
+async function witnessNative(browser, name, options) {
+    const localConfig = (0, witness_1.loadLocalConfig)(process.cwd());
+    const variant = options.variant ? variantSegment(options.variant) : (0, witness_1.nativeAppVariant)((0, witness_1.nativeAppDevice)(browser.capabilities));
+    if (variant)
+        name = `${name}__${variant}`;
+    const environment = (0, witness_1.appiumEnvironment)({
+        capabilities: browser.capabilities,
+        adapter: { name: '@testivai/witness-webdriverio', version: ADAPTER_VERSION, captureMethod: witness_1.CAPTURE_METHODS.APPIUM_SCREEN },
+        framework: { name: 'webdriverio', version: (0, witness_1.installedPackageVersion)('webdriverio') },
+    });
+    name = (0, witness_1.applyEnvironmentPolicyToName)(name, { browser: { name: environment.browser.name }, os: { platform: process.platform } }, localConfig.environmentPolicy);
+    const statusBar = options.maskStatusBar === false ? null : await statusBarHeight(browser);
+    const base64 = await browser.takeScreenshot();
+    if (typeof base64 !== 'string' || base64.length === 0) {
+        throw new Error(`testivai.witness("${name}"): browser.takeScreenshot() returned an empty value`);
+    }
+    const store = new witness_1.BaselineStore(process.cwd());
+    // Nothing from an earlier capture of this name: no DOM, element map or metadata.
+    for (const leftover of [store.getTempDomPath(name), store.getTempMetadataPath(name), path.join(store.getTempDir(), name, 'elements.json')]) {
+        fs.rmSync(leftover, { force: true });
+    }
+    store.writeTemp(name, Buffer.from(base64, 'base64'));
+    store.writeTempMetadata(name, { name, environment, ...(statusBar ? { masks: [{ top: statusBar }] } : {}) });
+}
+/** Sessions whose `mobile: getSystemBars` failed: not asked again, as WebdriverIO resends a failed command. */
+const withoutSystemBars = new WeakSet();
+/**
+ * The status bar's height in screenshot pixels for the mask, or null.
+ *
+ * On Android, the bar's window frame from the window manager at capture time
+ * (`mobile: getSystemBars`). UiAutomator2's own figure (`mobile: viewportRect`,
+ * then the capabilities) is read once, when the session starts, from a
+ * resource of its server app: on an Android 14 emulator it came back 63 px for
+ * a 136 px bar in one CI run, and it does not follow a rotation. It is the
+ * fallback, and the iOS source.
+ */
+async function statusBarHeight(browser) {
+    if ((0, witness_1.mobilePlatform)(browser.capabilities) === 'android' && !withoutSystemBars.has(browser)) {
+        try {
+            const fromWindowManager = (0, witness_1.statusBarFromSystemBars)(await browser.execute('mobile: getSystemBars'));
+            if (fromWindowManager !== null)
+                return fromWindowManager;
+        }
+        catch {
+            withoutSystemBars.add(browser);
+        }
+    }
+    try {
+        const fromViewport = (0, witness_1.statusBarFromViewportRect)(await browser.execute('mobile: viewportRect'));
+        if (fromViewport !== null)
+            return fromViewport;
+    }
+    catch {
+        // older drivers: the capabilities' reading from the session start
+    }
+    return (0, witness_1.statusBarFromCapabilities)(browser.capabilities);
+}
 /**
  * Capture a screenshot + DOM and write them as a temp snapshot.
  *
@@ -132,16 +227,91 @@ async function witness(browser, name, options = {}) {
     if (!browser || typeof browser.takeScreenshot !== 'function') {
         throw new Error('testivai.witness: browser argument must expose takeScreenshot()');
     }
+    if (options.context !== undefined) {
+        return inContext(browser, options.context, (native) => capture(browser, name, { ...options, native: options.native ?? native }));
+    }
+    return capture(browser, name, options);
+}
+/** A context as Appium names it: a string, or WebdriverIO's detailed `{ id }`. */
+const contextName = (c) => typeof c === 'string' ? c : typeof c?.id === 'string' ? c.id : '';
+/**
+ * Run a capture in another Appium context and switch back afterwards, also
+ * when it fails. `'webview'` is the web view named after the app (Android
+ * names it WEBVIEW_<package>), else the first one (iOS numbers them).
+ * Native mode follows the context: NATIVE_APP is native, any other is a page.
+ */
+async function inContext(browser, wanted, run) {
+    if (typeof browser.getContext !== 'function' || typeof browser.getContexts !== 'function' || typeof browser.switchContext !== 'function') {
+        throw new Error('testivai.witness: options.context needs an Appium session: browser.getContext(), getContexts() and switchContext()');
+    }
+    const contexts = (await browser.getContexts()).map(contextName).filter((c) => c.length > 0);
+    const current = contextName(await browser.getContext());
+    let target;
+    if (wanted === 'webview') {
+        const views = contexts.filter((c) => c.startsWith('WEBVIEW'));
+        const caps = (browser.capabilities ?? {});
+        const app = caps.appPackage ?? caps['appium:appPackage'] ?? caps.bundleId ?? caps['appium:bundleId'];
+        target = views.find((c) => typeof app === 'string' && c === `WEBVIEW_${app}`) ?? views[0];
+        if (!target) {
+            throw new Error(`testivai.witness: options.context 'webview': no web view context in this session (contexts: ${contexts.join(', ') || 'none'}). ` +
+                "The app's build needs WebView debugging enabled (Android WebView.setWebContentsDebuggingEnabled, iOS isInspectable), and the web view must be on screen.");
+        }
+    }
+    else {
+        target = wanted;
+        if (!contexts.includes(target)) {
+            throw new Error(`testivai.witness: options.context: no context "${wanted}" in this session (contexts: ${contexts.join(', ') || 'none'})`);
+        }
+    }
+    const switched = target !== current && current.length > 0;
+    if (target !== current)
+        await browser.switchContext(target);
+    try {
+        await run(target === 'NATIVE_APP');
+    }
+    catch (err) {
+        // Back where the test was; the capture error is the one that matters.
+        if (switched)
+            await browser.switchContext(current).catch(() => undefined);
+        throw err;
+    }
+    // A failed switch back leaves the session elsewhere: let it surface.
+    if (switched)
+        await browser.switchContext(current);
+}
+/** One capture in the session's current context: native mode or a page. */
+async function capture(browser, name, options) {
+    if (await isNativeCapture(browser, options.native)) {
+        return witnessNative(browser, name, options);
+    }
     // Multi-capability runs: fold the variant into the name so capabilities
     // don't overwrite each other's baselines (same mechanism as the Playwright
     // adapter's multi-project handling).
     if (options.variant) {
-        name = `${name}__${options.variant.replace(/[^a-z0-9_-]+/gi, '_').toLowerCase()}`;
+        name = `${name}__${variantSegment(options.variant)}`;
+    }
+    const localConfig = (0, witness_1.loadLocalConfig)(process.cwd());
+    // Capture provenance: what the page is rendered with, measured before
+    // anything is injected, plus the session's capabilities. Best-effort.
+    let renderProbe = null;
+    if (typeof browser.execute === 'function') {
+        try {
+            renderProbe = await browser.execute(`return ${witness_1.RENDER_PROBE_EXPRESSION}`);
+        }
+        catch {
+            // no probe: no render settings recorded
+        }
     }
+    const environment = (0, witness_1.webDriverEnvironment)({
+        capabilities: browser.capabilities,
+        probe: renderProbe,
+        adapter: { name: '@testivai/witness-webdriverio', version: ADAPTER_VERSION, captureMethod: witness_1.CAPTURE_METHODS.WEBDRIVER_VIEWPORT },
+        framework: { name: 'webdriverio', version: (0, witness_1.installedPackageVersion)('webdriverio') },
+    });
+    name = (0, witness_1.applyEnvironmentPolicyToName)(name, { browser: { name: environment?.browser.name ?? 'unknown' }, os: { platform: process.platform } }, localConfig.environmentPolicy);
     // 0. Prepare the page: stabilization CSS (animations/caret/fonts — the
     //    flake killers) + ignoreSelectors from config.json and this call,
     //    injected as one style tag and removed after the capture.
-    const localConfig = (0, witness_1.loadLocalConfig)(process.cwd());
     const stabilize = options.stabilize ?? localConfig.stabilize;
     const ignoreSelectors = [
         ...new Set([...(localConfig.ignoreSelectors ?? []), ...(options.ignoreSelectors ?? [])]),
@@ -197,10 +367,13 @@ async function witness(browser, name, options = {}) {
     //    It powers the style check, region attribution and page-shift
     //    detection on the compare side. The screenshot is the viewport, so the
     //    map keeps only the elements inside it, in screenshot coordinates.
+    // Opt-in: paths anchored on attributes such as data-testid (config
+    // `elementIdAttributes`), recorded with the capture only when set.
+    const idAttributes = (0, witness_1.normalizeElementIdAttributes)(localConfig.elementIdAttributes);
     let elementMap;
     if (!options.skipElementMap && typeof browser.execute === 'function') {
         try {
-            const result = await browser.execute((0, element_map_1.elementMapScript)(options.maxElements ?? witness_1.DEFAULT_MAX_ELEMENTS, ignoreSelectors));
+            const result = await browser.execute((0, element_map_1.elementMapScript)(options.maxElements ?? witness_1.DEFAULT_MAX_ELEMENTS, ignoreSelectors, idAttributes));
             if ((0, element_map_1.isPageElementMap)(result)) {
                 const inView = (0, element_map_1.toViewportElementMap)(result);
                 if (inView.length > 0)
@@ -215,11 +388,21 @@ async function witness(browser, name, options = {}) {
     // 4. Write to .testivai/temp/<name>/
     const store = new witness_1.BaselineStore(process.cwd());
     store.writeTemp(name, screenshot, dom);
+    if (environment) {
+        try {
+            store.writeTempMetadata(name, { name, environment });
+        }
+        catch {
+            // without it the compare cannot tell rendering drift from noise for this capture
+        }
+    }
     if (elementMap) {
         try {
             const tempDir = path.join(process.cwd(), '.testivai', 'temp', name);
             fs.mkdirSync(tempDir, { recursive: true });
             fs.writeFileSync(path.join(tempDir, 'elements.json'), JSON.stringify(elementMap));
+            if (idAttributes.length > 0)
+                store.writeTempMetadata(name, { elementIdAttributes: idAttributes });
         }
         catch {
             // A map we cannot persist is not worth failing a capture over.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-webdriverio",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "WebdriverIO adapter for TestivAI Witness — local-first visual regression with pixel + DOM comparison",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -54,7 +54,7 @@
     }
   },
   "dependencies": {
-    "@testivai/witness": "2.4.0"
+    "@testivai/witness": "2.6.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",