nativeproof 0.10.1 → 0.10.3

package/CHANGELOG.md

@@ -4,6 +4,45 @@ 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.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.
+
+**Added**
+
+- `defineApp` (and `createHarness` / `defineConfig`) are now generic over the mock type. An app
+  whose mock extends the base contract gets that concrete type through screens, login/join,
+  teardown, `onFailure` and the session context — no casts. Existing single-type-arg uses are
+  unchanged (the mock type defaults to `MockBackend`).
+- The synthesised runner config captures evidence on a failed behaviour out of the box — a
+  screenshot + redacted page source named after the spec — so apps need no hand-written
+  `afterTest`. Best-effort: a capture error never masks the real failure.
+
 ## 0.10.1
 
 Cross-platform locator resolution fixes.

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.
  *
@@ -10,53 +10,84 @@ import type { MockBackend } from "./mock.js";
  * framework core imports nothing from the app; the app describes itself here once.
  * `app.session(role)` turns that into a {@link ScenarioFixture} the `test` facade runs.
  */
-/** The device handles every session provides before app screens are layered on. */
-export interface DeviceContext {
+/**
+ * The device handles every session provides before app screens are layered on.
+ * 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. 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 SessionMock = SessionMock> {
     driver: Driver;
-    mock: MockBackend;
+    mock: M;
 }
 /** A screen-object factory: given the device context, build that screen's locators/actions. */
-export type ScreenFactory<S> = (context: DeviceContext) => S;
-export type ScreenFactories = Record<string, ScreenFactory<unknown>>;
+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 = DeviceContext & {
+export type FlowContext<M extends SessionMock = SessionMock> = DeviceContext<M> & {
     role: string;
 };
-export interface AppDefinition<S extends ScreenFactories> {
+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. */
-    mock: () => MockBackend | Promise<MockBackend>;
+    /** Start the app's mock backend (its concrete type `M` flows through the whole session). */
+    mock: () => M | Promise<M>;
     /** App-specific secret patterns to keep out of evidence (injected, never baked into the core). */
     secrets?: readonly RegExp[];
     /** App-specific evidence-redaction patterns. */
     redact?: readonly RegExp[];
     /** Reach a logged-in state for the role. */
-    login?: (context: FlowContext) => Promise<void>;
+    login?: (context: NoInfer<FlowContext<M>>) => Promise<void>;
     /** Enter the role's main surface. */
-    join?: (context: FlowContext) => 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>) => 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>, 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> = DeviceContext & {
+/** 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> {
+}>;
+/**
+ * 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>>;
+    session(role?: string): ScenarioFixture<Ctx>;
 }
-export declare function defineApp<S extends ScreenFactories>(definition: AppDefinition<S>): App<S>;
+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,4 +1,4 @@
-import type { App, ScreenFactories } from "./app.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
@@ -29,9 +29,20 @@ 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>;
 }
+/**
+ * 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"). */
@@ -43,12 +54,12 @@ export interface RunnerConfig {
     /** Per-test timeout in ms (default 240000). */
     mochaTimeout?: number;
 }
-export interface NativeProofConfig<S extends ScreenFactories = ScreenFactories> extends RunnerConfig {
+export interface NativeProofConfig<Ctx = unknown> extends RunnerConfig {
     /** The app under test (from `defineApp`). */
-    app: App<S>;
+    app: App<Ctx>;
 }
 /** Identity helper for typed config + editor autocomplete (mirrors Playwright's `defineConfig`). */
-export declare function defineConfig<S extends ScreenFactories>(config: NativeProofConfig<S>): NativeProofConfig<S>;
+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;

package/dist/config.js

@@ -1,5 +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;
@@ -39,10 +50,19 @@ export function buildWdioConfig(config, env = {}, cwd = process.cwd()) {
         path: env.appiumPath ?? config.appium?.path ?? "/wd/hub",
         specs,
         maxInstances: 1,
-        capabilities: [project.capabilities],
+        capabilities: [{ ...defaultCapabilities(project.platform), ...project.capabilities }],
         framework: "mocha",
         reporters: ["spec"],
         mochaOpts: { ui: "bdd", timeout: config.mochaTimeout ?? 240_000 },
+        // Evidence on failure, out of the box: on a failed behaviour, snapshot a screenshot +
+        // redacted page source into the artifact dir, named after the spec. Best-effort — a
+        // capture error never masks the real failure — and consumers get it without writing
+        // their own afterTest hook.
+        afterTest: async (test, _context, result) => {
+            if (result.passed)
+                return;
+            await captureState(failureEvidenceName(test)).catch(() => { });
+        },
     };
 }
 const CONFIG_NAMES = [

package/dist/evidence.d.ts

@@ -3,3 +3,13 @@ export declare function captureText(filename: string, contents: string): Promise
 export declare function captureScreenshot(filename: string): Promise<string>;
 /** Capture a screenshot + redacted source pair under one prefix; returns the source. */
 export declare function captureState(prefix: string): Promise<string>;
+/**
+ * A filesystem-safe evidence prefix for a failed behaviour — `failure-<describe>-<test>`
+ * with runs of non-word characters collapsed to `_` and capped at 120 chars. Used by the
+ * runner's built-in on-failure capture so a failing spec leaves a screenshot + source pair
+ * named after it, with no per-spec wiring.
+ */
+export declare function failureEvidenceName(test: {
+    parent: string;
+    title: string;
+}): string;

package/dist/evidence.js

@@ -42,3 +42,12 @@ export async function captureState(prefix) {
     await captureText(`${prefix}.xml`, source);
     return source;
 }
+/**
+ * A filesystem-safe evidence prefix for a failed behaviour — `failure-<describe>-<test>`
+ * with runs of non-word characters collapsed to `_` and capped at 120 chars. Used by the
+ * runner's built-in on-failure capture so a failing spec leaves a screenshot + source pair
+ * named after it, with no per-spec wiring.
+ */
+export function failureEvidenceName(test) {
+    return `failure-${test.parent}-${test.title}`.replace(/[^\w.-]+/g, "_").slice(0, 120);
+}

package/dist/harness.d.ts

@@ -1,4 +1,4 @@
-import type { App, ScreenFactories, SessionContext } from "./app.js";
+import type { App } from "./app.js";
 import { expect } from "./expect.js";
 /**
  * `createHarness(app)` — the Playwright `@playwright/test` pattern.
@@ -18,19 +18,28 @@ import { expect } from "./expect.js";
  * });
  * ```
  */
-export interface HarnessTest<S extends ScreenFactories> {
-    (name: string, body: (context: SessionContext<S>) => 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>) => 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>) => void | Promise<void>): void;
+    afterEach(body: (context: Ctx) => void | Promise<void>): void;
 }
-export interface Harness<S extends ScreenFactories> {
-    test: HarnessTest<S>;
+export interface Harness<Ctx> {
+    test: HarnessTest<Ctx>;
     expect: typeof expect;
 }
-export declare function createHarness<S extends ScreenFactories>(app: App<S>): Harness<S>;
+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.1",
+  "version": "0.10.3",
   "license": "MIT",
   "type": "module",
   "description": "Native Mobile E2E test framework inspired by Playwright (fixtures, locators, expect, route-style mocking) on Appium/WebdriverIO.",