nativeproof 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.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

@@ -10,31 +10,36 @@ 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 MockBackend}) 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.
+ */
+export interface DeviceContext<M extends MockBackend = MockBackend> {
     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 MockBackend = MockBackend> = (context: DeviceContext<M>) => S;
+export type ScreenFactories<M extends MockBackend = MockBackend> = Record<string, ScreenFactory<unknown, M>>;
 /** Context passed to the login/join flows. */
-export type FlowContext = DeviceContext & {
+export type FlowContext<M extends MockBackend = MockBackend> = DeviceContext<M> & {
     role: string;
 };
-export interface AppDefinition<S extends ScreenFactories> {
+export interface AppDefinition<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
     /** 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: FlowContext<M>) => Promise<void>;
     /** Enter the role's main surface. */
-    join?: (context: FlowContext) => Promise<void>;
+    join?: (context: FlowContext<M>) => Promise<void>;
     /** Screen-object factories, bound to the device context. */
     screens: S;
     /**
@@ -43,20 +48,20 @@ export interface AppDefinition<S extends ScreenFactories> {
      * so its background sockets are gone before `deleteSession`. The mock is still stopped
      * even if this throws.
      */
-    teardown?: (context: SessionContext<S>) => Promise<void> | void;
+    teardown?: (context: 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.
      */
-    onFailure?: (context: SessionContext<S>, info: FailureInfo) => Promise<void> | void;
+    onFailure?: (context: 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 & {
+export type SessionContext<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> = DeviceContext<M> & {
     [K in keyof S]: ReturnType<S[K]>;
 };
-export interface App<S extends ScreenFactories> {
+export interface App<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
     /** A scenario fixture that provisions a logged-in, joined session for `role`. */
-    session(role?: string): ScenarioFixture<SessionContext<S>>;
+    session(role?: string): ScenarioFixture<SessionContext<S, M>>;
 }
-export declare function defineApp<S extends ScreenFactories>(definition: AppDefinition<S>): App<S>;
+export declare function defineApp<S extends ScreenFactories<M>, M extends MockBackend = MockBackend>(definition: AppDefinition<S, M>): App<S, M>;

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import type { App, ScreenFactories } from "./app.js";
+import type { MockBackend } from "./mock.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
@@ -43,12 +44,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<S extends ScreenFactories<M> = ScreenFactories, M extends MockBackend = MockBackend> extends RunnerConfig {
     /** The app under test (from `defineApp`). */
-    app: App<S>;
+    app: App<S, M>;
 }
 /** 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<S extends ScreenFactories<M> = ScreenFactories, M extends MockBackend = MockBackend>(config: NativeProofConfig<S, M>): NativeProofConfig<S, M>;
 /** 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,6 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
+import { captureState, failureEvidenceName } from "./evidence.js";
 /** Identity helper for typed config + editor autocomplete (mirrors Playwright's `defineConfig`). */
 export function defineConfig(config) {
     return config;
@@ -43,6 +44,15 @@ export function buildWdioConfig(config, env = {}, cwd = process.cwd()) {
         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,5 +1,6 @@
 import type { App, ScreenFactories, SessionContext } from "./app.js";
 import { expect } from "./expect.js";
+import type { MockBackend } from "./mock.js";
 /**
  * `createHarness(app)` — the Playwright `@playwright/test` pattern.
  *
@@ -18,19 +19,19 @@ import { expect } from "./expect.js";
  * });
  * ```
  */
-export interface HarnessTest<S extends ScreenFactories> {
-    (name: string, body: (context: SessionContext<S>) => void | Promise<void>): void;
+export interface HarnessTest<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
+    (name: string, body: (context: SessionContext<S, M>) => 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: SessionContext<S, M>) => 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: SessionContext<S, M>) => void | Promise<void>): void;
 }
-export interface Harness<S extends ScreenFactories> {
-    test: HarnessTest<S>;
+export interface Harness<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
+    test: HarnessTest<S, M>;
     expect: typeof expect;
 }
-export declare function createHarness<S extends ScreenFactories>(app: App<S>): Harness<S>;
+export declare function createHarness<S extends ScreenFactories<M>, M extends MockBackend = MockBackend>(app: App<S, M>): Harness<S, M>;

package/package.json

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