lynkeus 0.2.0 → 0.4.0

package/lib/cases/runner.d.ts

@@ -1,10 +1,28 @@
 import { type AppEvent, type RunEvent } from '../knowledge/events.js';
 import { type Base, type Command } from '../registry.js';
 import type { Fixtures, FixturesConfig } from './fixtures.js';
-import { type Case, type StepValue } from './format.js';
+import { type BackendSpan, type TraceSink } from './traces.js';
+import { type Case, type Scope, type StepValue } from './format.js';
+export type NativeMock = {
+    result?: unknown;
+    screen?: {
+        title?: string;
+        subtitle?: string;
+        image?: string;
+        buttons?: Record<string, unknown>;
+    };
+};
 export type CasesConfig = {
     /** The folder of the file that declared this, set when the configuration is read. */
     base?: string;
+    /**
+     * What native SDKs a headless host cannot run answer, keyed `Module.method` (the native module's name, as
+     * `NativeModules` has it): `result` is what the call resolves with; `screen` puts up a stand-in page with a
+     * `title`, an optional `subtitle` and `image` (a URI), and `buttons`, label to result, each pressable as
+     * `#native-mock-<label>`. Sent to the app at the start of every case; a step changes it with
+     * `app.call: { command: nativeMocks, params: { set: { … } } }`, and `null` takes a key's mock away.
+     */
+    nativeMocks?: Record<string, NativeMock | null>;
     /** Where cases live (default `cases`). */
     dir?: string;
     /** Where the flows a case runs live (default `flows`). */
@@ -24,17 +42,33 @@ export type CasesConfig = {
         unless?: string;
     }[];
 };
+/** What a host's analytics capture saw a step send: the SDK it went to and the event. */
+export type SentEvent = {
+    provider: string;
+    name: string;
+    props?: Record<string, unknown>;
+};
+/** `unsupported`: the host the case ran on has no such thing to do (a real device has no mocked responses), which says nothing about the app. */
 export type StepReport = {
     step: string;
-    status: 'passed' | 'failed' | 'skipped';
+    status: 'passed' | 'failed' | 'skipped' | 'unsupported';
     ms: number;
     error?: string;
+    /** A frame of the screen once the step was done, an absolute path. */
+    screenshot?: string;
+    /** The second of the case's film at which the step began. */
+    videoS?: number;
+    /** What the step made the app send its analytics SDKs, where the host captures them. */
+    sent?: SentEvent[];
+    /** What the backend did for it, from the traces it exported to the run. */
+    backend?: BackendSpan[];
 };
 export type CaseReport = {
     id: string;
     title?: string;
     file: string;
-    result: 'passed' | 'failed';
+    /** `unsupported`: a step could not be done on this host, so the case proved nothing here; it did not fail. */
+    result: 'passed' | 'failed' | 'unsupported';
     ms: number;
     steps: StepReport[];
     /** When a step failed: the screen, the requests since the mark, and why. */
@@ -45,17 +79,62 @@ export type CaseReport = {
     };
     /** What the app told its analytics, each with the step that caused it, when the run asked for it. */
     events?: RunEvent[];
+    /** The case's film, an absolute path, where the host films. */
+    video?: string;
+    /** Every screen the app went through while the case ran, when the run asked for them (`routes`). */
+    routes?: string[];
+    /** Why it failed, read as rules from the screen, the requests and the trace (`lynkeus why`). */
+    diagnosis?: string[];
+};
+/** Where a case keeps what it can show of itself: a frame per step, a film. Each is taken only where the host can. */
+export type Evidence = {
+    dir: string;
+    screenshots?: boolean;
+    settleMs?: number;
+    video?: {
+        fps: number;
+        scale?: number;
+    };
 };
 export type RunOptions = {
     base: Base;
+    /** Where the backend's traces arrive during the run: each app step's requests carry its id. */
+    traces?: TraceSink;
     config: CasesConfig;
     fixtures?: Fixtures;
     dry?: boolean;
     events?: boolean;
+    evidence?: Evidence;
     log?: (line: string) => void;
+    /** The case's setup, already run by `case prepare`: the case starts from here. */
+    prepared?: Prepared;
+    /** Run only the setup and hand what it left to `keep`, for a case that will run later. */
+    setupOnly?: {
+        keep: (prepared: Prepared) => void;
+    };
+    /** Keep running a case's steps after one fails, to see everything that is wrong in one pass. */
+    continue?: boolean;
+    /** Collect the screens the app went through, for a coverage map. `fresh`: the app was started for this case. */
+    routes?: boolean | 'fresh';
+};
+/** What a case's setup leaves for its steps: the aliases and what they answered, and what ran. */
+export type Prepared = {
+    scope: Scope;
+    latest: Record<string, unknown>;
+    ran: string[];
+    steps: StepReport[];
 };
+/** A setup made only of the project's fixtures can run before the case, with no app attached. */
+export declare const preparable: (c: Case, config: CasesConfig) => boolean;
 /** What a buffer holds that it did not before, whichever end it grows from. */
 export declare const newSince: (before: AppEvent[], now: AppEvent[]) => AppEvent[];
 /** A step's value as the argv of the command it names: what matches a positional by name goes in place, the rest are flags. */
 export declare const argvFor: (command: Command, value: StepValue) => string[];
+/**
+ * The fixtures a case names that the project's server did not list. A macro's
+ * own steps are the project's to keep right; these are the ones written in the case.
+ */
+export declare const missingFixtures: (c: Case, config: CasesConfig, known: string[]) => string[];
+/** What the app or its host answers to a method it does not have; the name is what it lacks. */
+export declare const lacking: (message: string) => string | undefined;
 export declare const runCase: (c: Case, options: RunOptions) => Promise<CaseReport>;