@testingbot/mobilewright-driver 0.1.0 → 0.2.0

package/dist/session-commands.d.ts

@@ -0,0 +1,75 @@
+import type { TestingBotDriver } from './driver.js';
+/** @internal — called by TestingBotDriver.connect()/disconnect(). */
+export declare function setActiveDriver(driver: TestingBotDriver | undefined): void;
+/** Network conditions accepted by `testingbot.throttle()`. */
+export type ThrottlePreset = 'Edge' | '3G' | '4G' | 'airplane' | 'disable';
+export interface ThrottleProfile {
+    downloadSpeed?: number;
+    uploadSpeed?: number;
+    latency?: number;
+    loss?: number;
+    disable?: boolean;
+}
+/**
+ * TestingBot-specific commands, callable from inside a mobilewright test:
+ *
+ *   import { testingbot } from '@testingbot/mobilewright-driver';
+ *   await testingbot.throttle('3G');
+ */
+export declare const testingbot: {
+    /**
+     * Change network conditions mid-test (`tb:throttle`). Pass a preset
+     * ("Edge", "3G", "4G", "airplane", "disable") or a custom profile.
+     * Throttling is reset automatically when the test's device session is
+     * released, so it cannot leak into the next test on a pooled device.
+     */
+    throttle(conditions: ThrottlePreset | ThrottleProfile): Promise<void>;
+    /**
+     * Run an ADB shell command on Android (`mobile: shell`). Physical devices
+     * allow a whitelisted subset (am/pm/input/getprop/settings/dumpsys, ...);
+     * emulators allow everything.
+     */
+    shell<T = unknown>(command: string, args?: string[]): Promise<T>;
+    /**
+     * Name this session on the TestingBot dashboard (`tb:test-name`). Useful
+     * per test — see the README recipe for naming every session from a
+     * `beforeEach`. In pooled mode the last test to run on a session wins.
+     */
+    setName(name: string): Promise<void>;
+    /** Group this session under a build on the dashboard (`tb:test-build`). */
+    setBuild(build: string): Promise<void>;
+    /** Tag this session (`tb:test-tags`). */
+    setTags(tags: string[]): Promise<void>;
+    /**
+     * Mark the session passed or failed (`tb:test-result`). The driver already
+     * reports the run's verdict automatically — use this only to override it,
+     * e.g. to fail a session for a reason mobilewright cannot see.
+     */
+    setResult(passed: boolean | "passed" | "failed"): Promise<void>;
+    /**
+     * Log a step into the session's command list (`tb:test-context`), so the
+     * TestingBot timeline shows what the test was doing at that point.
+     */
+    annotate(context: string): Promise<void>;
+    /** Update several session fields at once (`tb:test-info`). */
+    updateInfo(info: {
+        name?: string;
+        build?: string;
+        public?: boolean;
+        statusMessage?: string;
+        extra?: string;
+    }): Promise<void>;
+    /**
+     * Pause the session for manual inspection (`tb:break`) — the test result
+     * page offers a live view with mouse/keyboard control. Debugging only: it
+     * blocks until you resume, so never leave it in CI.
+     */
+    breakpoint(): Promise<void>;
+    /** Escape hatch: run any Appium or TestingBot execute-script command. */
+    execute<T = unknown>(script: string, ...args: unknown[]): Promise<T>;
+    /** WebDriver session id of the device this test is running on. */
+    sessionId(): string;
+    /** Link to this test's session on the TestingBot dashboard. */
+    dashboardUrl(): string;
+};
+//# sourceMappingURL=session-commands.d.ts.map

package/dist/session-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-commands.d.ts","sourceRoot":"","sources":["../src/session-commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAYpD,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,GAAG,IAAI,CAE1E;AAYD,8DAA8D;AAC9D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,UAAU,GAAG,SAAS,CAAC;AAC3E,MAAM,WAAW,eAAe;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU;IACrB;;;;;OAKG;yBACwB,cAAc,GAAG,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3E;;;;OAIG;UACS,CAAC,qBAAqB,MAAM,SAAQ,MAAM,EAAE,GAAQ,OAAO,CAAC,CAAC,CAAC;IAI1E;;;;OAIG;kBACiB,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C,2EAA2E;oBACrD,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,yCAAyC;kBACrB,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C;;;;OAIG;sBACqB,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrE;;;OAGG;sBACqB,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,8DAA8D;qBACvC;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjB;;;;OAIG;kBACiB,OAAO,CAAC,IAAI,CAAC;IAIjC,yEAAyE;YAC3D,CAAC,oBAAoB,MAAM,WAAW,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IAI1E,kEAAkE;iBACrD,MAAM;IAInB,+DAA+D;oBAC/C,MAAM;CAGvB,CAAC"}

package/dist/session-commands.js

@@ -0,0 +1,119 @@
+/**
+ * The driver instance currently connected in THIS process. mobilewright loads
+ * `mobilewright.config.ts` in every worker and connects the driver instance it
+ * exports, and test files run in that same worker process — so tests can reach
+ * the live session through this registry without mobilewright needing to pass
+ * the driver through its fixtures. Workers are single-test-at-a-time, so one
+ * slot is enough; parallel workers are separate processes with their own.
+ */
+let active;
+/** @internal — called by TestingBotDriver.connect()/disconnect(). */
+export function setActiveDriver(driver) {
+    active = driver;
+}
+function requireActive(command) {
+    if (!active) {
+        throw new Error(`TestingBot: ${command} needs a connected device session. Call it inside a test body ` +
+            '(mobilewright connects the device before the test runs), not at module scope.');
+    }
+    return active;
+}
+/**
+ * TestingBot-specific commands, callable from inside a mobilewright test:
+ *
+ *   import { testingbot } from '@testingbot/mobilewright-driver';
+ *   await testingbot.throttle('3G');
+ */
+export const testingbot = {
+    /**
+     * Change network conditions mid-test (`tb:throttle`). Pass a preset
+     * ("Edge", "3G", "4G", "airplane", "disable") or a custom profile.
+     * Throttling is reset automatically when the test's device session is
+     * released, so it cannot leak into the next test on a pooled device.
+     */
+    async throttle(conditions) {
+        await requireActive('throttle()').throttle(conditions);
+    },
+    /**
+     * Run an ADB shell command on Android (`mobile: shell`). Physical devices
+     * allow a whitelisted subset (am/pm/input/getprop/settings/dumpsys, ...);
+     * emulators allow everything.
+     */
+    async shell(command, args = []) {
+        return await requireActive('shell()').executeScript('mobile: shell', { command, args });
+    },
+    /**
+     * Name this session on the TestingBot dashboard (`tb:test-name`). Useful
+     * per test — see the README recipe for naming every session from a
+     * `beforeEach`. In pooled mode the last test to run on a session wins.
+     */
+    async setName(name) {
+        await requireActive('setName()').executeScript(`tb:test-name=${oneLine(name)}`);
+    },
+    /** Group this session under a build on the dashboard (`tb:test-build`). */
+    async setBuild(build) {
+        await requireActive('setBuild()').executeScript(`tb:test-build=${oneLine(build)}`);
+    },
+    /** Tag this session (`tb:test-tags`). */
+    async setTags(tags) {
+        await requireActive('setTags()').executeScript(`tb:test-tags=${tags.map(oneLine).join(',')}`);
+    },
+    /**
+     * Mark the session passed or failed (`tb:test-result`). The driver already
+     * reports the run's verdict automatically — use this only to override it,
+     * e.g. to fail a session for a reason mobilewright cannot see.
+     */
+    async setResult(passed) {
+        const value = typeof passed === 'string' ? passed : (passed ? 'passed' : 'failed');
+        await requireActive('setResult()').executeScript(`tb:test-result=${value}`);
+    },
+    /**
+     * Log a step into the session's command list (`tb:test-context`), so the
+     * TestingBot timeline shows what the test was doing at that point.
+     */
+    async annotate(context) {
+        await requireActive('annotate()').executeScript(`tb:test-context=${oneLine(context)}`);
+    },
+    /** Update several session fields at once (`tb:test-info`). */
+    async updateInfo(info) {
+        const payload = {};
+        if (info.name !== undefined)
+            payload['name'] = oneLine(info.name);
+        if (info.build !== undefined)
+            payload['build'] = oneLine(info.build);
+        if (info.public !== undefined)
+            payload['public'] = info.public;
+        // The hub decodeURIComponent()s these two — send them encoded so a stray
+        // '%' in the text cannot make the whole update throw server-side.
+        if (info.statusMessage !== undefined)
+            payload['status_message'] = encodeURIComponent(info.statusMessage);
+        if (info.extra !== undefined)
+            payload['extra'] = encodeURIComponent(info.extra);
+        await requireActive('updateInfo()').executeScript(`tb:test-info=${JSON.stringify(payload)}`);
+    },
+    /**
+     * Pause the session for manual inspection (`tb:break`) — the test result
+     * page offers a live view with mouse/keyboard control. Debugging only: it
+     * blocks until you resume, so never leave it in CI.
+     */
+    async breakpoint() {
+        await requireActive('breakpoint()').executeScript('tb:break');
+    },
+    /** Escape hatch: run any Appium or TestingBot execute-script command. */
+    async execute(script, ...args) {
+        return await requireActive('execute()').executeScript(script, ...args);
+    },
+    /** WebDriver session id of the device this test is running on. */
+    sessionId() {
+        return requireActive('sessionId()').currentSessionId();
+    },
+    /** Link to this test's session on the TestingBot dashboard. */
+    dashboardUrl() {
+        return `https://testingbot.com/members/tests/${this.sessionId()}`;
+    },
+};
+/** tb: commands are string-encoded, so newlines would corrupt the payload. */
+function oneLine(value) {
+    return value.replace(/\s*\n\s*/g, ' ').trim();
+}
+//# sourceMappingURL=session-commands.js.map

package/dist/session-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-commands.js","sourceRoot":"","sources":["../src/session-commands.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testingbot/mobilewright-driver",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TestingBot driver for Mobilewright — run mobilewright tests on TestingBot's device cloud",
   "homepage": "https://testingbot.com",
   "license": "Apache-2.0",