nativeproof 0.1.1

package/dist/cli.d.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * The `nativeproof` CLI — the single-command entry, in the spirit of `playwright test`.
+ *
+ * It resolves a config (an `nativeproof.config.ts`, else a raw `wdio.conf.ts`), ensures an
+ * Appium server is up (starting one if needed), and runs the suite with sane env
+ * (PLATFORM / SPEC / NATIVEPROOF_PROJECT / APPIUM_*) — so a consumer types one command
+ * instead of remembering env vars and a runner invocation. The device/emulator itself is
+ * the environment (the mobile analogue of needing a display) and is left to the host.
+ */
+export interface CliArgs {
+    command: "test" | "help" | "version";
+    config: string | undefined;
+    platform: "android" | "ios" | undefined;
+    project: string | undefined;
+    spec: string | undefined;
+    appiumHost: string;
+    appiumPort: number;
+    appiumPath: string;
+    startAppium: boolean;
+}
+export declare function parseArgs(argv: readonly string[]): CliArgs;
+export declare function version(): string;
+export declare function helpText(): string;
+interface ResolvedRunner {
+    wdioConfig: string;
+    extraEnv: NodeJS.ProcessEnv;
+}
+/** Pick what to hand WebdriverIO: an explicit config, an nativeproof.config.ts, or wdio.conf.ts. */
+export declare function resolveRunner(args: CliArgs, cwd?: string): ResolvedRunner;
+export declare function main(argv: readonly string[]): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findConfigFile } from "./config.js";
+const DEFAULTS = {
+    command: "test",
+    config: undefined,
+    platform: undefined,
+    project: undefined,
+    spec: undefined,
+    appiumHost: "127.0.0.1",
+    appiumPort: 4723,
+    appiumPath: "/wd/hub",
+    startAppium: true,
+};
+function valueFor(argv, index, flag) {
+    const value = argv[index];
+    if (value === undefined)
+        throw new Error(`${flag} requires a value`);
+    return value;
+}
+export function parseArgs(argv) {
+    const args = { ...DEFAULTS };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "test")
+            continue;
+        if (arg === "-h" || arg === "--help")
+            return { ...args, command: "help" };
+        if (arg === "-v" || arg === "--version")
+            return { ...args, command: "version" };
+        if (arg === "--no-appium") {
+            args.startAppium = false;
+        }
+        else if (arg === "--config") {
+            i += 1;
+            args.config = valueFor(argv, i, "--config");
+        }
+        else if (arg === "--project") {
+            i += 1;
+            args.project = valueFor(argv, i, "--project");
+        }
+        else if (arg === "--spec") {
+            i += 1;
+            args.spec = valueFor(argv, i, "--spec");
+        }
+        else if (arg === "--platform") {
+            i += 1;
+            const platform = valueFor(argv, i, "--platform");
+            if (platform !== "android" && platform !== "ios") {
+                throw new Error('--platform must be "android" or "ios"');
+            }
+            args.platform = platform;
+        }
+        else if (arg === "--appium-host") {
+            i += 1;
+            args.appiumHost = valueFor(argv, i, "--appium-host");
+        }
+        else if (arg === "--appium-port") {
+            i += 1;
+            args.appiumPort = Number(valueFor(argv, i, "--appium-port"));
+        }
+        else if (arg === "--appium-path") {
+            i += 1;
+            args.appiumPath = valueFor(argv, i, "--appium-path");
+        }
+        else {
+            throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    return args;
+}
+export function version() {
+    try {
+        const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+        const pkg = JSON.parse(raw);
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export function helpText() {
+    return [
+        "nativeproof — Native Mobile E2E test framework inspired by Playwright",
+        "",
+        "Usage:",
+        "  nativeproof [test] [options]",
+        "",
+        "Config is auto-discovered: nativeproof.config.ts (preferred), else wdio.conf.ts.",
+        "",
+        "Options:",
+        "  --platform <android|ios>   platform to run (sets PLATFORM)",
+        "  --project <name>           run a named project from nativeproof.config.ts",
+        "  --spec <glob>              run only matching specs (sets SPEC)",
+        "  --config <path>            use a raw WebdriverIO config instead of discovery",
+        "  --appium-host <host>       Appium host (default: 127.0.0.1)",
+        "  --appium-port <port>       Appium port (default: 4723)",
+        "  --appium-path <path>       Appium base path (default: /wd/hub)",
+        "  --no-appium                do not auto-start an Appium server",
+        "  -h, --help                 show this help",
+        "  -v, --version              print the version",
+    ].join("\n");
+}
+function localBin(name) {
+    const bin = path.join(process.cwd(), "node_modules", ".bin", name);
+    return existsSync(bin) ? bin : name;
+}
+async function appiumReachable(args) {
+    try {
+        const response = await fetch(`http://${args.appiumHost}:${args.appiumPort}${args.appiumPath}/status`, {
+            signal: AbortSignal.timeout(1500),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureAppium(args) {
+    if (await appiumReachable(args))
+        return null;
+    if (!args.startAppium) {
+        throw new Error(`Appium is not reachable at http://${args.appiumHost}:${args.appiumPort}${args.appiumPath} (and --no-appium was set)`);
+    }
+    console.log("nativeproof: starting Appium …");
+    const child = spawn(localBin("appium"), ["--base-path", args.appiumPath, "--relaxed-security"], {
+        stdio: "ignore",
+    });
+    const deadline = Date.now() + 30_000;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        if (await appiumReachable(args))
+            return child;
+    }
+    child.kill();
+    throw new Error("nativeproof: Appium did not become reachable within 30s");
+}
+function runnerEnv(args) {
+    const env = {
+        ...process.env,
+        APPIUM_HOST: args.appiumHost,
+        APPIUM_PORT: String(args.appiumPort),
+        APPIUM_PATH: args.appiumPath,
+    };
+    if (args.platform)
+        env.PLATFORM = args.platform;
+    if (args.project)
+        env.NATIVEPROOF_PROJECT = args.project;
+    if (args.spec)
+        env.SPEC = args.spec;
+    return env;
+}
+/** Pick what to hand WebdriverIO: an explicit config, an nativeproof.config.ts, or wdio.conf.ts. */
+export function resolveRunner(args, cwd = process.cwd()) {
+    if (args.config) {
+        const resolved = path.resolve(cwd, args.config);
+        if (!existsSync(resolved))
+            throw new Error(`nativeproof: config not found: ${args.config}`);
+        return { wdioConfig: resolved, extraEnv: {} };
+    }
+    const nativeproofConfig = findConfigFile(cwd);
+    if (nativeproofConfig) {
+        return {
+            wdioConfig: fileURLToPath(new URL("./runner-config.js", import.meta.url)),
+            extraEnv: {
+                NATIVEPROOF_CONFIG: nativeproofConfig,
+                NODE_OPTIONS: `--import tsx ${process.env.NODE_OPTIONS ?? ""}`.trim(),
+            },
+        };
+    }
+    const wdioConf = path.resolve(cwd, "wdio.conf.ts");
+    if (existsSync(wdioConf))
+        return { wdioConfig: wdioConf, extraEnv: {} };
+    throw new Error("nativeproof: no nativeproof.config.ts or wdio.conf.ts found (pass --config <path>)");
+}
+async function runTests(args) {
+    const { wdioConfig, extraEnv } = resolveRunner(args);
+    const appium = await ensureAppium(args);
+    try {
+        return await new Promise((resolve, reject) => {
+            const runner = spawn(localBin("wdio"), ["run", wdioConfig], {
+                stdio: "inherit",
+                env: { ...runnerEnv(args), ...extraEnv },
+            });
+            runner.on("error", reject);
+            runner.on("exit", (code) => resolve(code ?? 1));
+        });
+    }
+    finally {
+        appium?.kill();
+    }
+}
+export async function main(argv) {
+    const args = parseArgs(argv);
+    if (args.command === "help") {
+        console.log(helpText());
+        return 0;
+    }
+    if (args.command === "version") {
+        console.log(version());
+        return 0;
+    }
+    return runTests(args);
+}
+/** True when this file is the process entry — robust to the symlink npm creates for bins. */
+function isCliEntry() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isCliEntry()) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,70 @@
+import type { App, ScreenFactories } 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
+ * synthesises the WebdriverIO run from it — so no hand-written `wdio.conf.ts`.
+ *
+ * ```ts
+ * // nativeproof.config.ts
+ * const app = defineApp({ ... });
+ * export const { test, expect } = createHarness(app);   // specs import these
+ * export default defineConfig({
+ *   app,
+ *   testDir: "tests",
+ *   projects: [
+ *     { name: "android", platform: "android", capabilities: { ... } },
+ *     { name: "ios", platform: "ios", capabilities: { ... } },
+ *   ],
+ * });
+ * ```
+ */
+/** Appium connection settings (defaults: 127.0.0.1 : 4723 /wd/hub). */
+export interface AppiumOptions {
+    host?: string;
+    port?: number;
+    path?: string;
+}
+/** One device target — the NativeProof analogue of a Playwright project. */
+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>;
+}
+/** 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"). */
+    testMatch?: string;
+    projects: DeviceProject[];
+    appium?: AppiumOptions;
+    /** Per-test timeout in ms (default 240000). */
+    mochaTimeout?: number;
+}
+export interface NativeProofConfig<S extends ScreenFactories = ScreenFactories> extends RunnerConfig {
+    /** The app under test (from `defineApp`). */
+    app: App<S>;
+}
+/** Identity helper for typed config + editor autocomplete (mirrors Playwright's `defineConfig`). */
+export declare function defineConfig<S extends ScreenFactories>(config: NativeProofConfig<S>): NativeProofConfig<S>;
+/** Selection inputs (from the CLI / env) used to resolve the active project + connection. */
+export interface RunnerEnv {
+    platform?: string;
+    project?: string;
+    spec?: string;
+    appiumHost?: string;
+    appiumPort?: number;
+    appiumPath?: string;
+}
+/** 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.
+ */
+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. */
+export declare function findConfigFile(dir: string, exists?: (file: string) => boolean): string | null;

package/dist/config.js

@@ -0,0 +1,64 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+/** Identity helper for typed config + editor autocomplete (mirrors Playwright's `defineConfig`). */
+export function defineConfig(config) {
+    return config;
+}
+/** Pick the project by explicit name, else by platform, else the first one. */
+export function resolveProject(config, env = {}) {
+    if (env.project) {
+        const named = config.projects.find((project) => project.name === env.project);
+        if (!named)
+            throw new Error(`nativeproof: no project named "${env.project}"`);
+        return named;
+    }
+    if (env.platform) {
+        const byPlatform = config.projects.find((project) => project.platform === env.platform);
+        if (byPlatform)
+            return byPlatform;
+    }
+    const first = config.projects[0];
+    if (!first)
+        throw new Error("nativeproof: config has no `projects`");
+    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.
+ */
+export function buildWdioConfig(config, env = {}, cwd = process.cwd()) {
+    const project = resolveProject(config, env);
+    const testDir = config.testDir ?? "tests";
+    const testMatch = config.testMatch ?? "**/*.spec.ts";
+    const specs = [path.resolve(cwd, env.spec ?? `${testDir}/${testMatch}`)];
+    return {
+        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,
+        maxInstances: 1,
+        capabilities: [project.capabilities],
+        framework: "mocha",
+        reporters: ["spec"],
+        mochaOpts: { ui: "bdd", timeout: config.mochaTimeout ?? 240_000 },
+    };
+}
+const CONFIG_NAMES = [
+    "nativeproof.config.ts",
+    "nativeproof.config.mts",
+    "nativeproof.config.cts",
+    "nativeproof.config.js",
+    "nativeproof.config.mjs",
+    "nativeproof.config.cjs",
+];
+/** Find an `nativeproof.config.*` in `dir`, or null. `exists` is injectable for testing. */
+export function findConfigFile(dir, exists = existsSync) {
+    for (const name of CONFIG_NAMES) {
+        const candidate = path.join(dir, name);
+        if (exists(candidate))
+            return candidate;
+    }
+    return null;
+}

package/dist/driver.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The minimal device contract the locator and expect layers drive.
+ *
+ * A thin seam over the real engine (WebdriverIO/Appium) — the Playwright `Page`
+ * equivalent — that keeps locators and matchers testable without a device: tests
+ * supply a fake `Driver`, production uses {@link wdioDriver}.
+ */
+export type Platform = "android" | "ios";
+export interface Driver {
+    /** The platform under test — selects how a cross-platform selector maps to source. */
+    readonly platform: Platform;
+    /** Current page-source XML (best-effort; empty string on driver error). */
+    source(): Promise<string>;
+    /** Idle for the given milliseconds; also used as the poll interval by the waits. */
+    pause(ms: number): Promise<void>;
+    /** Tap an absolute screen coordinate. */
+    tapAt(x: number, y: number): Promise<void>;
+}
+/** A {@link Driver} backed by the live WebdriverIO/Appium session. */
+export declare function wdioDriver(): Driver;

package/dist/driver.js

@@ -0,0 +1,13 @@
+import { browser } from "@wdio/globals";
+import { tapAt } from "./gestures.js";
+/** A {@link Driver} backed by the live WebdriverIO/Appium session. */
+export function wdioDriver() {
+    return {
+        get platform() {
+            return browser.isAndroid ? "android" : "ios";
+        },
+        source: () => browser.getPageSource().catch(() => ""),
+        pause: (ms) => browser.pause(ms),
+        tapAt: (x, y) => tapAt(x, y),
+    };
+}

package/dist/evidence.d.ts

@@ -0,0 +1,5 @@
+export declare function redactEvidenceText(contents: string): string;
+export declare function captureText(filename: string, contents: string): Promise<string>;
+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>;

package/dist/evidence.js

@@ -0,0 +1,40 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { browser } from "@wdio/globals";
+/**
+ * Test-time evidence capture: screenshots and redacted page-source snapshots.
+ *
+ * A passing mobile test must prove app state, not just "the runner did not throw".
+ * Every meaningful step writes a `.png` + redacted `.xml` pair into the artifact
+ * directory so a green run is auditable. Secrets are stripped before anything
+ * touches disk. Part of the reusable framework core.
+ */
+const artifactDir = process.env.E2E_ARTIFACT_DIR ?? ".e2e-artifacts";
+export function redactEvidenceText(contents) {
+    return String(contents)
+        .replace(/(text=")\d{4,8}(")/g, "$1[REDACTED]$2")
+        .replace(/(passcode"?\s*[:=]\s*"?)\d{4,8}/gi, "$1[REDACTED]")
+        .replace(/(Bearer\s+)[A-Za-z0-9._-]+/g, "$1[REDACTED]");
+}
+async function ensureArtifactDir() {
+    await fs.mkdir(artifactDir, { recursive: true });
+}
+export async function captureText(filename, contents) {
+    await ensureArtifactDir();
+    const target = path.join(artifactDir, filename);
+    await fs.writeFile(target, redactEvidenceText(contents), "utf8");
+    return target;
+}
+export async function captureScreenshot(filename) {
+    await ensureArtifactDir();
+    const target = path.join(artifactDir, filename);
+    await browser.saveScreenshot(target);
+    return target;
+}
+/** Capture a screenshot + redacted source pair under one prefix; returns the source. */
+export async function captureState(prefix) {
+    const source = await browser.getPageSource().catch(() => "");
+    await captureScreenshot(`${prefix}.png`);
+    await captureText(`${prefix}.xml`, source);
+    return source;
+}

package/dist/expect.d.ts

@@ -0,0 +1,26 @@
+import { Locator, type WaitOptions } from "./locator.js";
+import { type FrameMatch, type MockBackend } from "./mock.js";
+/**
+ * Playwright-style assertions with built-in auto-waiting — the "easy visibility"
+ * layer. `expect(locator)` asserts UI state; `expect(mock)` asserts backend traffic.
+ * Each matcher polls until the condition holds (or the timeout elapses), then asserts;
+ * `.not` inverts it. No manual waits in the spec.
+ */
+export interface LocatorAssertions {
+    readonly not: LocatorAssertions;
+    /** The selector matches a node in the source. */
+    toBeVisible(options?: WaitOptions): Promise<void>;
+    /** The selector is present and `text` is shown on screen. */
+    toShow(text: string | RegExp, options?: WaitOptions): Promise<void>;
+    /** The matched node's own text equals/contains/matches `text`. */
+    toHaveText(text: string | RegExp, options?: WaitOptions): Promise<void>;
+}
+export interface MockAssertions {
+    readonly not: MockAssertions;
+    /** The app sent a frame matching `match`. */
+    toHaveSent(match: FrameMatch, options?: WaitOptions): Promise<void>;
+    /** The app received a frame matching `match`. */
+    toHaveReceived(match: FrameMatch, options?: WaitOptions): Promise<void>;
+}
+export declare function expect(target: Locator): LocatorAssertions;
+export declare function expect(target: MockBackend): MockAssertions;

package/dist/expect.js

@@ -0,0 +1,65 @@
+import { describeSelector, Locator, waitUntil } from "./locator.js";
+import { describeMatch, frameExists } from "./mock.js";
+class LocatorExpectation {
+    locator;
+    negated;
+    constructor(locator, negated = false) {
+        this.locator = locator;
+        this.negated = negated;
+    }
+    get not() {
+        return new LocatorExpectation(this.locator, !this.negated);
+    }
+    toBeVisible(options = {}) {
+        return this.check(() => this.locator.isVisible(), "be visible", options);
+    }
+    toShow(text, options = {}) {
+        return this.check(() => this.locator.shows(text), `show ${JSON.stringify(String(text))}`, options);
+    }
+    toHaveText(text, options = {}) {
+        return this.check(async () => {
+            const content = await this.locator.textContent();
+            if (content === null)
+                return false;
+            return typeof text === "string" ? content.includes(text) : text.test(content);
+        }, `have text ${JSON.stringify(String(text))}`, options);
+    }
+    async check(predicate, description, options) {
+        const want = !this.negated;
+        const opts = { ...options, sleep: (ms) => this.locator.driver.pause(ms) };
+        const settled = await waitUntil(predicate, (value) => value === want, opts);
+        if (settled !== want) {
+            const not = this.negated ? ".not" : "";
+            throw new Error(`expect(${describeSelector(this.locator.selector)})${not}.to ${description} — assertion not met`);
+        }
+    }
+}
+class MockExpectation {
+    mock;
+    negated;
+    constructor(mock, negated = false) {
+        this.mock = mock;
+        this.negated = negated;
+    }
+    get not() {
+        return new MockExpectation(this.mock, !this.negated);
+    }
+    toHaveSent(match, options = {}) {
+        return this.check("sent", match, options);
+    }
+    toHaveReceived(match, options = {}) {
+        return this.check("received", match, options);
+    }
+    async check(direction, match, options) {
+        const want = !this.negated;
+        const settled = await waitUntil(() => frameExists(this.mock, direction, match), (value) => value === want, options);
+        if (settled !== want) {
+            const not = this.negated ? ".not" : "";
+            const matcher = direction === "sent" ? "toHaveSent" : "toHaveReceived";
+            throw new Error(`expect(mock)${not}.${matcher}(${describeMatch(match)}) — assertion not met`);
+        }
+    }
+}
+export function expect(target) {
+    return target instanceof Locator ? new LocatorExpectation(target) : new MockExpectation(target);
+}

package/dist/fixtures.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Playwright-style behaviour fixtures for Appium/WebdriverIO + Mocha.
+ *
+ * Gives specs the developer experience of Playwright — a typed fixture context
+ * injected into each behaviour, with provisioning and teardown owned by the
+ * framework instead of copy-pasted into every `before`/`after` — without depending
+ * on Playwright itself (which cannot drive native iOS/Android). It is a thin layer
+ * over whatever BDD runner hosts it (Mocha by default; see {@link runner}).
+ *
+ * App-agnostic by contract: nothing here may import app-specific code. A caller
+ * supplies a {@link ScenarioFixture} describing how to provision and tear down its
+ * own context (start a mock, relaunch the app, log in, join …); this module only
+ * wires that lifecycle into the runner and injects the result. It is part of the
+ * surface intended for extraction into a standalone package.
+ */
+/**
+ * Provisioning + teardown for one behaviour scenario's shared fixture context.
+ *
+ * The context is provisioned ONCE per scenario (Mocha `before`) and shared across
+ * its ordered behaviours, then torn down ONCE (`after`) — the analogue of a
+ * Playwright scoped fixture or `describe.serial`. This suits stateful mobile
+ * sessions where a single login+join underpins many in-session behaviours:
+ * re-provisioning per behaviour would be prohibitively slow and would change what
+ * is asserted, because the behaviours accumulate session state in a deliberate
+ * order. A per-behaviour-isolation mode can layer on later for stateless scenarios
+ * without changing this contract.
+ *
+ * @typeParam Ctx - the fixture context injected into each behaviour.
+ */
+export interface ScenarioFixture<Ctx> {
+    /** Provision the shared context (e.g. start mock, relaunch app, log in, join). */
+    setup(): Promise<Ctx>;
+    /**
+     * Release everything {@link ScenarioFixture.setup} acquired. Always invoked, even
+     * when `setup` threw partway, so it receives `undefined` if no context was
+     * produced and must be safe to call in that state.
+     */
+    teardown(context: Ctx | undefined): Promise<void>;
+}
+/**
+ * Registers one behaviour. The provisioned context is injected, so the body is pure
+ * behaviour — no `before`/`after`, no threading a backend handle through assertions.
+ * Read it Playwright-style: destructure the fixtures the behaviour needs.
+ */
+export type BehaviourRegistrar<Ctx> = (title: string, body: (context: Ctx) => void | Promise<void>) => void;
+/**
+ * Define a behaviour scenario: a Mocha `describe` whose fixture context is
+ * provisioned once, injected into every behaviour, and torn down once.
+ *
+ * @param title   - the scenario description (Mocha `describe` title).
+ * @param fixture - how to provision and tear down the shared context.
+ * @param define  - registers the behaviours; receives a `test` registrar that
+ *                  injects the context.
+ *
+ * @example
+ * describeScenario("chat room", chatRoomScenario(), (test) => {
+ *   test("renders the latest message", async ({ member }) => {
+ *     await member.assertLatestMessageVisible();
+ *   });
+ * });
+ */
+export declare function describeScenario<Ctx>(title: string, fixture: ScenarioFixture<Ctx>, define: (test: BehaviourRegistrar<Ctx>) => void): void;