nativeproof 0.10.2 → 0.10.4

package/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to NativeProof are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## 0.10.4
+
+Per-project spec sets and WebdriverIO tuning pass-through, for suites that run a different set of
+specs per platform and need longer timeouts on slow devices.
+
+**Added**
+
+- `DeviceProject.specs` — per-project spec globs that override the top-level `testDir`/`testMatch`,
+  for suites where platforms run different specs (e.g. a shared set plus a platform-specific set:
+  `["e2e/shared/**\/*.spec.ts", "e2e/android/**\/*.spec.ts"]`). A `--spec` CLI override still wins.
+  Precedence: `--spec` (comma-separated) > `project.specs` > `testDir`/`testMatch`.
+- WebdriverIO tuning pass-throughs on `RunnerConfig`: `connectionRetryTimeout`,
+  `connectionRetryCount`, `waitforTimeout`, `bail`, and `logLevel`. Each is forwarded to the
+  synthesised WebdriverIO config only when set, so WebdriverIO's own defaults apply otherwise —
+  slow software-GPU emulators in particular often need longer connection/wait timeouts. `bail: 0`
+  is meaningful (never bail) and is still forwarded.
+
+## 0.10.3
+
+Out-of-the-box setup: scaffolding, minimal config, a route-optional mock contract, and typed
+contexts across the `createHarness` export boundary.
+
+**Added**
+
+- `nativeproof init` scaffolds a starter `nativeproof.config.ts` (app + harness + android/ios
+  projects) and a sample spec, so a new project is runnable in one command. Idempotent — it
+  never overwrites an existing file.
+- `defineApp` now accepts any mock that exposes `frames()` + `stop()` (the new `SessionMock`);
+  `route()` is no longer required, since a session never routes (only a spec does). An app whose
+  mock only observes traffic can use `defineApp` / `createHarness` / `nativeproof.config` directly.
+- `buildWdioConfig` fills in `platformName` and `appium:automationName` per platform (Android →
+  UiAutomator2, iOS → XCUITest), so a project needs only `name` + `platform`. A project's own
+  capabilities still win, and `DeviceProject.capabilities` is now optional.
+
+**Fixed**
+
+- `export const { test } = createHarness(app)` consumed from a spec in another file now keeps a
+  fully-typed fixture context. The harness/app/config are parameterised by the *resolved* context
+  rather than the screens type `S` (which TS widened to its constraint — screens → `unknown` — when
+  computing the exported type), so behaviours get typed `mock` and screens across the import
+  boundary. `App<S, M>` is now `App<Ctx>`; `NativeProofConfig` / `defineConfig` follow.
+
 ## 0.10.2
 
 Generic mock typing and built-in evidence-on-failure.

package/README.md

@@ -100,7 +100,13 @@ npx appium driver doctor uiautomator2
 
 ## Quick start
 
-Four steps from zero to a green run on Android.
+Scaffold the starting files with one command, then fill in your app's seam:
+
+```bash
+npx nativeproof init   # writes nativeproof.config.ts + a sample spec (never overwrites)
+```
+
+Then four steps from zero to a green run on Android — or set it all up by hand:
 
 **1. Configure** — one `nativeproof.config.ts` at the project root:
 

package/dist/app.d.ts

@@ -1,6 +1,6 @@
 import type { Driver } from "./driver.js";
 import type { FailureInfo, ScenarioFixture } from "./fixtures.js";
-import type { MockBackend } from "./mock.js";
+import type { SessionMock } from "./mock.js";
 /**
  * `defineApp` — the single seam script.
  *
@@ -12,22 +12,23 @@ import type { MockBackend } from "./mock.js";
  */
 /**
  * The device handles every session provides before app screens are layered on.
- * Generic over the mock type `M` (default {@link MockBackend}) so an app with a richer
+ * Generic over the mock type `M` (default {@link SessionMock}) so an app with a richer
  * mock — extra socket/presence controls beyond the base contract — gets `mock` typed as
- * that richer type throughout, with no casts. Existing one-arg uses keep the base mock.
+ * that richer type throughout, with no casts. The constraint is `SessionMock` (frames + stop),
+ * not the full `MockBackend`, so a mock that doesn't implement `route()` still works.
  */
-export interface DeviceContext<M extends MockBackend = MockBackend> {
+export interface DeviceContext<M extends SessionMock = SessionMock> {
     driver: Driver;
     mock: M;
 }
 /** A screen-object factory: given the device context, build that screen's locators/actions. */
-export type ScreenFactory<S, M extends MockBackend = MockBackend> = (context: DeviceContext<M>) => S;
-export type ScreenFactories<M extends MockBackend = MockBackend> = Record<string, ScreenFactory<unknown, M>>;
+export type ScreenFactory<S, M extends SessionMock = SessionMock> = (context: DeviceContext<M>) => S;
+export type ScreenFactories<M extends SessionMock = SessionMock> = Record<string, ScreenFactory<unknown, M>>;
 /** Context passed to the login/join flows. */
-export type FlowContext<M extends MockBackend = MockBackend> = DeviceContext<M> & {
+export type FlowContext<M extends SessionMock = SessionMock> = DeviceContext<M> & {
     role: string;
 };
-export interface AppDefinition<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
+export interface AppDefinition<S extends ScreenFactories<M>, M extends SessionMock = SessionMock> {
     /** Acquire the device/driver (e.g. wdioDriver()). */
     driver: () => Driver | Promise<Driver>;
     /** Start the app's mock backend (its concrete type `M` flows through the whole session). */
@@ -37,31 +38,56 @@ export interface AppDefinition<S extends ScreenFactories<M>, M extends MockBacke
     /** App-specific evidence-redaction patterns. */
     redact?: readonly RegExp[];
     /** Reach a logged-in state for the role. */
-    login?: (context: FlowContext<M>) => Promise<void>;
+    login?: (context: NoInfer<FlowContext<M>>) => Promise<void>;
     /** Enter the role's main surface. */
-    join?: (context: FlowContext<M>) => Promise<void>;
-    /** Screen-object factories, bound to the device context. */
+    join?: (context: NoInfer<FlowContext<M>>) => Promise<void>;
+    /** Screen-object factories, bound to the device context. `S` (and so the whole context) is
+     *  inferred from here. */
     screens: S;
     /**
      * Release app-level resources acquired across the session, run on teardown BEFORE the
      * mock stops and before the runner deletes the device session — e.g. force-stop the app
      * so its background sockets are gone before `deleteSession`. The mock is still stopped
      * even if this throws.
+     *
+     * The context is wrapped in `NoInfer` so passing a `teardown` does NOT drive `S` inference —
+     * otherwise this S-dependent parameter co-infers with `screens` and collapses `S` to its
+     * `ScreenFactories<M>` constraint (screens → `unknown`) in the exported context type.
      */
-    teardown?: (context: SessionContext<S, M>) => Promise<void> | void;
+    teardown?: (context: NoInfer<SessionContext<S, M>>) => Promise<void> | void;
     /**
      * Invoked when a behaviour throws, before the failure propagates — wire on-failure
      * evidence here (e.g. `captureState(...)`) so capture lives in one place, not in every
-     * behaviour. Its own errors are swallowed so they never mask the real failure.
+     * behaviour. Its own errors are swallowed so they never mask the real failure. `NoInfer` for the
+     * same reason as `teardown` — this parameter must not participate in inferring `S`.
      */
-    onFailure?: (context: SessionContext<S, M>, info: FailureInfo) => Promise<void> | void;
+    onFailure?: (context: NoInfer<SessionContext<S, M>>, info: FailureInfo) => Promise<void> | void;
 }
-/** The fixture context a session injects: the device handles plus each app screen. */
-export type SessionContext<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> = DeviceContext<M> & {
+/** Eagerly flatten an intersection into one object type, so the resolved context ports cleanly. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * The fixture context a session injects: the device handles plus each app screen's value. Flattened
+ * with {@link Prettify} so it is a single object type rather than a lazy intersection — that lets
+ * `export const { test } = createHarness(app)` carry fully-typed screens into specs in other files.
+ * (Portability still needs the mock type `M` to be nameable — a single exported interface, not an
+ * anonymous intersection — so a consumer's mock should be one named type.)
+ */
+export type SessionContext<S extends ScreenFactories<M>, M extends SessionMock = SessionMock> = Prettify<DeviceContext<M> & {
     [K in keyof S]: ReturnType<S[K]>;
-};
-export interface App<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
+}>;
+/**
+ * Parameterised by the *resolved* session context `Ctx` (`{ driver; mock; …screens }`), not by
+ * the screens type `S`. `S` is only ever used inside the mapped `SessionContext<S, M>`, a
+ * non-inferable position — so a consumer's `export const { test } = createHarness(app)` would
+ * lose the concrete screen return types across the import boundary (TS falls back to the
+ * `ScreenFactories<M>` constraint, whose screens are `unknown`). `defineApp` resolves the context
+ * here, where `S` is still concrete, so `Ctx` is a plain object type that ports cleanly into specs.
+ */
+export interface App<Ctx> {
     /** A scenario fixture that provisions a logged-in, joined session for `role`. */
-    session(role?: string): ScenarioFixture<SessionContext<S, M>>;
+    session(role?: string): ScenarioFixture<Ctx>;
 }
-export declare function defineApp<S extends ScreenFactories<M>, M extends MockBackend = MockBackend>(definition: AppDefinition<S, M>): App<S, M>;
+export declare function defineApp<S extends ScreenFactories<M>, M extends SessionMock = SessionMock>(definition: AppDefinition<S, M>): App<SessionContext<S, M>>;
+export {};

package/dist/app.js

@@ -12,7 +12,8 @@ export function defineApp(definition) {
                         if (definition.join)
                             await definition.join({ ...device, role });
                         const screens = {};
-                        for (const [name, factory] of Object.entries(definition.screens)) {
+                        const factories = Object.entries(definition.screens);
+                        for (const [name, factory] of factories) {
                             screens[name] = factory(device);
                         }
                         // Dynamic assembly: the screen factories' precise return types are

package/dist/cli.d.ts

@@ -9,7 +9,7 @@
  * the environment (the mobile analogue of needing a display) and is left to the host.
  */
 export interface CliArgs {
-    command: "test" | "help" | "version";
+    command: "test" | "init" | "help" | "version";
     config: string | undefined;
     platform: "android" | "ios" | undefined;
     project: string | undefined;
@@ -22,6 +22,23 @@ export interface CliArgs {
 export declare function parseArgs(argv: readonly string[]): CliArgs;
 export declare function version(): string;
 export declare function helpText(): string;
+export interface ScaffoldFile {
+    path: string;
+    contents: string;
+}
+/** The starter files \`nativeproof init\` writes — pure, so they can be asserted in a test. */
+export declare function scaffoldFiles(): ScaffoldFile[];
+/** Minimal filesystem seam so \`scaffold\` is testable without touching disk. */
+export interface ScaffoldIo {
+    exists(file: string): boolean;
+    write(file: string, contents: string): void;
+}
+/** Write the starter files under \`cwd\`, never overwriting an existing one. */
+export declare function scaffold(cwd: string, io?: ScaffoldIo): {
+    created: string[];
+    skipped: string[];
+};
+export declare function init(cwd?: string): number;
 interface ResolvedRunner {
     wdioConfig: string;
     extraEnv: NodeJS.ProcessEnv;

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { findConfigFile } from "./config.js";
@@ -27,6 +27,10 @@ export function parseArgs(argv) {
         const arg = argv[i];
         if (arg === "test")
             continue;
+        if (arg === "init") {
+            args.command = "init";
+            continue;
+        }
         if (arg === "-h" || arg === "--help")
             return { ...args, command: "help" };
         if (arg === "-v" || arg === "--version")
@@ -92,7 +96,8 @@ export function helpText() {
         "nativeproof — Native Mobile E2E test framework inspired by Playwright",
         "",
         "Usage:",
-        "  nativeproof [test] [options]",
+        "  nativeproof [test] [options]   run the suite (default)",
+        "  nativeproof init               scaffold nativeproof.config.ts + a sample spec",
         "",
         "Config is auto-discovered: nativeproof.config.ts (preferred), else wdio.conf.ts.",
         "",
@@ -109,6 +114,88 @@ export function helpText() {
         "  -v, --version              print the version",
     ].join("\n");
 }
+const CONFIG_TEMPLATE = `import { createHarness, defineApp, defineConfig, page, startMockServer, wdioDriver } from "nativeproof";
+
+/**
+ * One file declares your app, your devices, and where your specs live — the
+ * \`nativeproof\` CLI discovers it and runs the suite. Replace the TODOs with your app.
+ */
+const app = defineApp({
+  // Acquire the device/driver (Appium/WebdriverIO under the hood).
+  driver: () => wdioDriver(),
+  // Start a mock backend; swap startMockServer() for your own if you have one.
+  mock: () => startMockServer(),
+  // Screen objects: build locators/actions from the device context. Replace these.
+  screens: {
+    home: ({ driver }) => ({
+      heading: page(driver).getByText("Welcome"),
+    }),
+  },
+});
+
+// Specs import these: \`import { test, expect } from "../nativeproof.config";\`
+export const { test, expect } = createHarness(app);
+
+export default defineConfig({
+  app,
+  testDir: "tests",
+  // platformName + automationName are filled in from \`platform\`; set \`appium:app\` to your build.
+  projects: [
+    { name: "android", platform: "android", capabilities: { /* "appium:app": "/path/to/app.apk" */ } },
+    { name: "ios", platform: "ios", capabilities: { /* "appium:app": "/path/to/app.app" */ } },
+  ],
+});
+`;
+const SPEC_TEMPLATE = `import { expect, test } from "../nativeproof.config";
+
+test.describe("example", () => {
+  test("the home screen shows its heading", async ({ home }) => {
+    await expect(home.heading).toBeVisible();
+  });
+});
+`;
+/** The starter files \`nativeproof init\` writes — pure, so they can be asserted in a test. */
+export function scaffoldFiles() {
+    return [
+        { path: "nativeproof.config.ts", contents: CONFIG_TEMPLATE },
+        { path: "tests/example.spec.ts", contents: SPEC_TEMPLATE },
+    ];
+}
+const diskIo = {
+    exists: existsSync,
+    write(file, contents) {
+        mkdirSync(path.dirname(file), { recursive: true });
+        writeFileSync(file, contents);
+    },
+};
+/** Write the starter files under \`cwd\`, never overwriting an existing one. */
+export function scaffold(cwd, io = diskIo) {
+    const created = [];
+    const skipped = [];
+    for (const file of scaffoldFiles()) {
+        if (io.exists(path.join(cwd, file.path))) {
+            skipped.push(file.path);
+            continue;
+        }
+        io.write(path.join(cwd, file.path), file.contents);
+        created.push(file.path);
+    }
+    return { created, skipped };
+}
+export function init(cwd = process.cwd()) {
+    const { created, skipped } = scaffold(cwd);
+    for (const file of created)
+        console.log(`nativeproof: created ${file}`);
+    for (const file of skipped)
+        console.log(`nativeproof: ${file} already exists — skipped`);
+    if (created.length === 0) {
+        console.log("nativeproof: nothing to scaffold (all files already exist)");
+    }
+    else {
+        console.log("\nNext: set capabilities + screens in nativeproof.config.ts, then run `nativeproof`.");
+    }
+    return 0;
+}
 function localBin(name) {
     const bin = path.join(process.cwd(), "node_modules", ".bin", name);
     return existsSync(bin) ? bin : name;
@@ -208,6 +295,9 @@ export async function main(argv) {
         console.log(version());
         return 0;
     }
+    if (args.command === "init") {
+        return init();
+    }
     return runTests(args);
 }
 /** True when this file is the process entry — robust to the symlink npm creates for bins. */

package/dist/config.d.ts

@@ -1,5 +1,4 @@
-import type { App, ScreenFactories } from "./app.js";
-import type { MockBackend } from "./mock.js";
+import type { App } from "./app.js";
 /**
  * The Playwright-style config: one `nativeproof.config.ts` declares the app, the device
  * projects, and where the tests live. The `nativeproof` CLI auto-discovers it and
@@ -30,26 +29,59 @@ export interface DeviceProject {
     /** A name to select with `nativeproof --project <name>`. */
     name: string;
     platform: "android" | "ios";
-    /** Appium capabilities for this device (e.g. `appium:app`, `appium:deviceName`). */
-    capabilities: Record<string, unknown>;
+    /**
+     * Appium capabilities for this device (e.g. `appium:app`, `appium:deviceName`). Optional:
+     * `platformName` and `appium:automationName` are filled in from `platform` (see
+     * {@link defaultCapabilities}), so a project usually needs only `appium:app` — or nothing
+     * for a smoke run against whatever is already installed. Anything you set here wins.
+     */
+    capabilities?: Record<string, unknown>;
+    /**
+     * Spec globs for THIS project, relative to the project root — overriding the top-level
+     * `testDir`/`testMatch` when set. For suites where platforms run different specs (e.g. a shared
+     * set plus a platform-specific set: `["e2e/shared/**\/*.spec.ts", "e2e/android/**\/*.spec.ts"]`).
+     * A `--spec` CLI override still wins over this.
+     */
+    specs?: string[];
 }
+/**
+ * The standard capabilities for a platform, so a consumer doesn't restate the same
+ * `platformName` / `automationName` in every project. Android → UiAutomator2, iOS → XCUITest
+ * (the canonical Appium drivers). A project's own `capabilities` override these.
+ */
+export declare function defaultCapabilities(platform: "android" | "ios"): Record<string, unknown>;
 /** The device/run config the CLI turns into a WebdriverIO run. */
 export interface RunnerConfig {
     /** Directory holding the specs (default "tests"). */
     testDir?: string;
-    /** Glob within `testDir` (default "**\/*.spec.ts"). */
+    /** Glob within `testDir` (default "**\/*.spec.ts"). A project's own `specs` overrides this. */
     testMatch?: string;
     projects: DeviceProject[];
     appium?: AppiumOptions;
     /** Per-test timeout in ms (default 240000). */
     mochaTimeout?: number;
+    /**
+     * WebdriverIO pass-throughs for tuning real-device runs. Each is forwarded only when set, so
+     * WebdriverIO's own defaults apply otherwise. Slow software-GPU emulators in particular often
+     * need a longer `connectionRetryTimeout` / `waitforTimeout` than the defaults.
+     */
+    /** Per-command/session connection timeout in ms (wdio default 120000). */
+    connectionRetryTimeout?: number;
+    /** Connection retry count (wdio default 3). */
+    connectionRetryCount?: number;
+    /** Default auto-wait timeout in ms for `waitUntil`/`waitFor*` (wdio default 5000). */
+    waitforTimeout?: number;
+    /** Stop the run after N failures; 0 = never bail (wdio default 0). */
+    bail?: number;
+    /** WebdriverIO log level (wdio default "info"). */
+    logLevel?: "trace" | "debug" | "info" | "warn" | "error" | "silent";
 }
-export interface NativeProofConfig<S extends ScreenFactories<M> = ScreenFactories, M extends MockBackend = MockBackend> extends RunnerConfig {
+export interface NativeProofConfig<Ctx = unknown> extends RunnerConfig {
     /** The app under test (from `defineApp`). */
-    app: App<S, M>;
+    app: App<Ctx>;
 }
 /** Identity helper for typed config + editor autocomplete (mirrors Playwright's `defineConfig`). */
-export declare function defineConfig<S extends ScreenFactories<M> = ScreenFactories, M extends MockBackend = MockBackend>(config: NativeProofConfig<S, M>): NativeProofConfig<S, M>;
+export declare function defineConfig<Ctx>(config: NativeProofConfig<Ctx>): NativeProofConfig<Ctx>;
 /** Selection inputs (from the CLI / env) used to resolve the active project + connection. */
 export interface RunnerEnv {
     platform?: string;
@@ -62,9 +94,7 @@ export interface RunnerEnv {
 /** Pick the project by explicit name, else by platform, else the first one. */
 export declare function resolveProject(config: RunnerConfig, env?: RunnerEnv): DeviceProject;
 /**
- * Translate an NativeProof config into a WebdriverIO `config` object. Spec paths are made
- * absolute against `cwd` (the project root) because the synthesised config is loaded from
- * inside `node_modules`, so a relative glob would resolve against the wrong directory.
+ * Translate an NativeProof config into a WebdriverIO `config` object.
  */
 export declare function buildWdioConfig(config: RunnerConfig, env?: RunnerEnv, cwd?: string): Record<string, unknown>;
 /** Find an `nativeproof.config.*` in `dir`, or null. `exists` is injectable for testing. */

package/dist/config.js

@@ -1,6 +1,16 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { captureState, failureEvidenceName } from "./evidence.js";
+/**
+ * The standard capabilities for a platform, so a consumer doesn't restate the same
+ * `platformName` / `automationName` in every project. Android → UiAutomator2, iOS → XCUITest
+ * (the canonical Appium drivers). A project's own `capabilities` override these.
+ */
+export function defaultCapabilities(platform) {
+    return platform === "android"
+        ? { platformName: "Android", "appium:automationName": "UiAutomator2" }
+        : { platformName: "iOS", "appium:automationName": "XCUITest" };
+}
 /** Identity helper for typed config + editor autocomplete (mirrors Playwright's `defineConfig`). */
 export function defineConfig(config) {
     return config;
@@ -24,23 +34,34 @@ export function resolveProject(config, env = {}) {
     return first;
 }
 /**
- * Translate an NativeProof config into a WebdriverIO `config` object. Spec paths are made
- * absolute against `cwd` (the project root) because the synthesised config is loaded from
- * inside `node_modules`, so a relative glob would resolve against the wrong directory.
+ * Resolve the spec globs (absolute) for a run, in precedence order: an explicit `--spec` override
+ * (comma-separated allowed), else the active project's own `specs`, else the top-level
+ * `testDir`/`testMatch`. Absolute against `cwd` because the synthesised config is loaded from inside
+ * `node_modules`, so a relative glob would resolve against the wrong directory.
  */
-export function buildWdioConfig(config, env = {}, cwd = process.cwd()) {
-    const project = resolveProject(config, env);
+function resolveSpecs(config, project, env, cwd) {
+    const abs = (glob) => path.resolve(cwd, glob);
+    if (env.spec)
+        return env.spec.split(",").map((glob) => abs(glob.trim()));
+    if (project.specs && project.specs.length > 0)
+        return project.specs.map(abs);
     const testDir = config.testDir ?? "tests";
     const testMatch = config.testMatch ?? "**/*.spec.ts";
-    const specs = [path.resolve(cwd, env.spec ?? `${testDir}/${testMatch}`)];
-    return {
+    return [abs(`${testDir}/${testMatch}`)];
+}
+/**
+ * Translate an NativeProof config into a WebdriverIO `config` object.
+ */
+export function buildWdioConfig(config, env = {}, cwd = process.cwd()) {
+    const project = resolveProject(config, env);
+    const wdio = {
         runner: "local",
         hostname: env.appiumHost ?? config.appium?.host ?? "127.0.0.1",
         port: env.appiumPort ?? config.appium?.port ?? 4723,
         path: env.appiumPath ?? config.appium?.path ?? "/wd/hub",
-        specs,
+        specs: resolveSpecs(config, project, env, cwd),
         maxInstances: 1,
-        capabilities: [project.capabilities],
+        capabilities: [{ ...defaultCapabilities(project.platform), ...project.capabilities }],
         framework: "mocha",
         reporters: ["spec"],
         mochaOpts: { ui: "bdd", timeout: config.mochaTimeout ?? 240_000 },
@@ -54,6 +75,19 @@ export function buildWdioConfig(config, env = {}, cwd = process.cwd()) {
             await captureState(failureEvidenceName(test)).catch(() => { });
         },
     };
+    // Optional WebdriverIO tuning — forwarded only when the consumer set it, so wdio's defaults apply
+    // otherwise (real emulators/simulators often need longer connection/wait timeouts than the defaults).
+    if (config.connectionRetryTimeout !== undefined)
+        wdio.connectionRetryTimeout = config.connectionRetryTimeout;
+    if (config.connectionRetryCount !== undefined)
+        wdio.connectionRetryCount = config.connectionRetryCount;
+    if (config.waitforTimeout !== undefined)
+        wdio.waitforTimeout = config.waitforTimeout;
+    if (config.bail !== undefined)
+        wdio.bail = config.bail;
+    if (config.logLevel !== undefined)
+        wdio.logLevel = config.logLevel;
+    return wdio;
 }
 const CONFIG_NAMES = [
     "nativeproof.config.ts",

package/dist/harness.d.ts

@@ -1,6 +1,5 @@
-import type { App, ScreenFactories, SessionContext } from "./app.js";
+import type { App } from "./app.js";
 import { expect } from "./expect.js";
-import type { MockBackend } from "./mock.js";
 /**
  * `createHarness(app)` — the Playwright `@playwright/test` pattern.
  *
@@ -19,19 +18,28 @@ import type { MockBackend } from "./mock.js";
  * });
  * ```
  */
-export interface HarnessTest<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
-    (name: string, body: (context: SessionContext<S, M>) => void | Promise<void>): void;
+/**
+ * Parameterised by the *resolved* session context `Ctx`, not by the screens type `S`. When a
+ * project does `export const { test } = createHarness(app)` and a spec in another file imports
+ * `test`, TS computes the portable exported type — and if the harness were parameterised by
+ * `S extends ScreenFactories<M>`, it would write the **constraint** (`ScreenFactories<M>`, whose
+ * screens return `unknown`) instead of the concrete `S`, so every imported behaviour's context
+ * would be `unknown`. `Ctx` is already the concrete object (`{ driver; mock; …screens }`), so the
+ * screen return types survive the boundary and behaviours stay fully typed.
+ */
+export interface HarnessTest<Ctx> {
+    (name: string, body: (context: Ctx) => void | Promise<void>): void;
     /** Open a scenario block for the default role. */
     describe(title: string, body: () => void): void;
     /** Open a scenario block for a specific role (e.g. "member" / "guest"). */
     describe(title: string, role: string, body: () => void): void;
     /** Run before each behaviour in the open scenario, with the session context injected. */
-    beforeEach(body: (context: SessionContext<S, M>) => void | Promise<void>): void;
+    beforeEach(body: (context: Ctx) => void | Promise<void>): void;
     /** Run after each behaviour in the open scenario, with the session context injected. */
-    afterEach(body: (context: SessionContext<S, M>) => void | Promise<void>): void;
+    afterEach(body: (context: Ctx) => void | Promise<void>): void;
 }
-export interface Harness<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
-    test: HarnessTest<S, M>;
+export interface Harness<Ctx> {
+    test: HarnessTest<Ctx>;
     expect: typeof expect;
 }
-export declare function createHarness<S extends ScreenFactories<M>, M extends MockBackend = MockBackend>(app: App<S, M>): Harness<S, M>;
+export declare function createHarness<Ctx>(app: App<Ctx>): Harness<Ctx>;

package/dist/mock.d.ts

@@ -43,12 +43,20 @@ export interface FrameLog {
     /** Every frame observed so far, in order, both directions. */
     frames(): Promise<readonly MockFrame[]>;
 }
-export interface MockBackend extends FrameLog {
-    /** Intercept a path and control its reply. */
-    route(path: string): MockRoute;
+/**
+ * The minimum a mock must provide to drive a {@link defineApp} session: observable frames plus a
+ * `stop()` the session calls on teardown. `route()` is intentionally NOT required — a session never
+ * routes (only a spec does) — so an app whose mock only observes frames and stops can use
+ * `defineApp` without implementing `route`. {@link MockBackend} is the full contract (adds `route`).
+ */
+export interface SessionMock extends FrameLog {
     /** Release the backend (stop the server, close sockets). */
     stop(): Promise<void>;
 }
+export interface MockBackend extends SessionMock {
+    /** Intercept a path and control its reply. */
+    route(path: string): MockRoute;
+}
 /**
  * True if `frame` satisfies every field of `match`: `path` / `type` at the top level,
  * every other key against the frame's payload.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nativeproof",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "license": "MIT",
   "type": "module",
   "description": "Native Mobile E2E test framework inspired by Playwright (fixtures, locators, expect, route-style mocking) on Appium/WebdriverIO.",