lynkeus-protocol 0.3.0 → 0.5.0

package/lib/fixtures.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The fixtures protocol: how a case prepares and reads a backend through a server the project writes. lynkeus starts
+ * the command `cases.fixtures` names and speaks JSON lines to it, one request and one answer per line.
+ * The full contract is docs/FIXTURES.md.
+ */
+export declare const FIXTURES_PROTOCOL = 1;
+/** One step, as lynkeus sends it: `params` as the case wrote them, `env` the same flattened to upper-case strings. */
+export type FixtureRequest = {
+    command: string;
+    params: Record<string, unknown>;
+    env: Record<string, string>;
+};
+/** Any JSON object; `ok: false` with an `error` when the step failed. */
+export type FixtureAnswer = {
+    ok?: boolean;
+    error?: string;
+} & Record<string, unknown>;
+/** A parameter a command takes, for authors and models choosing a setup. */
+export type FixtureParam = {
+    type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    summary?: string;
+    /** The values it takes, when they are few. */
+    values?: (string | number | boolean)[];
+    default?: unknown;
+    required?: boolean;
+};
+/** What a command does, for authors and models: what state it makes or reads, its parameters, one example. */
+export type FixtureCommand = {
+    name: string;
+    summary?: string;
+    params?: Record<string, FixtureParam>;
+    /** The params of one call that works, as a case would write them. */
+    example?: Record<string, unknown>;
+    /** What its answer carries that a later step reads (`user_id`, `api_key`…). */
+    answers?: string[];
+    /** `false` for a command that only reads: safe to call while checking a server. */
+    changes?: boolean;
+};
+/**
+ * The answer to `lynkeus.describe`. `commands` lists names, or descriptions, or both; a server from before
+ * descriptions answers names only, and that stays valid. `down` says the server runs but cannot serve.
+ */
+export type FixturesDescription = {
+    protocol?: number;
+    commands: (string | FixtureCommand)[];
+    down?: string;
+};

package/lib/fixtures.js

@@ -0,0 +1,6 @@
+/**
+ * The fixtures protocol: how a case prepares and reads a backend through a server the project writes. lynkeus starts
+ * the command `cases.fixtures` names and speaks JSON lines to it, one request and one answer per line.
+ * The full contract is docs/FIXTURES.md.
+ */
+export const FIXTURES_PROTOCOL = 1;

package/lib/index.d.ts

@@ -122,6 +122,11 @@ export type WaitForParams = {
     /** Swipe the nearest scrolling container towards the target until it is in the window. */
     scroll?: boolean;
     timeoutMs?: number;
+    /**
+     * A trace mark (`trace().last`): a `route` the app reached after it counts as arrived, even if the app has
+     * already left it. A screen that closes itself (a success screen) can come and go while a step's frame settles.
+     */
+    since?: number;
 };
 export type TraceEvent = {
     seq: number;
@@ -180,6 +185,12 @@ export type TraceEvent = {
     stack?: string;
     route?: string;
 });
+/** One side of a request: its headers and body, sensitive values replaced by `…`, a long body cut. */
+export type Exchange = {
+    headers?: Record<string, string>;
+    body?: string;
+    truncated?: boolean;
+};
 export type RequestRecord = {
     id: number;
     method: string;
@@ -188,6 +199,9 @@ export type RequestRecord = {
     startedAt: number;
     ms?: number;
     error?: string;
+    /** Only while a driver asked for bodies (`networkBodies`). */
+    request?: Exchange;
+    response?: Exchange;
 };
 /** Every method the core answers. Apps add their own through `qa.register`. */
 export type CoreMethods = {
@@ -262,7 +276,8 @@ export type CoreMethods = {
         result: {
             route?: string;
             matched?: Target;
-            waitedMs: number;
+            waitedMs: number /** The route was reached after `since` and left again. */;
+            passed?: boolean;
         };
     };
     idle: {
@@ -358,3 +373,4 @@ export type AuthEvent = {
 };
 export type AgentEvent = HelloEvent | NavigationEvent;
 export * from './run.js';
+export * from './fixtures.js';

package/lib/index.js

@@ -1,3 +1,4 @@
 /** JSON-RPC-shaped messages over a WebSocket the app opens towards the driver; docs/PROTOCOL.md has the prose. */
 export const PROTOCOL_VERSION = 1;
 export * from './run.js';
+export * from './fixtures.js';

package/lib/run.d.ts

@@ -1,3 +1,4 @@
+import type { RequestRecord } from './index.js';
 /**
  * What a run of cases leaves behind: a directory anything can read without
  * knowing how the run was made.
@@ -62,11 +63,31 @@ export type RunStep = {
     videoS?: number;
     /** What the backend did for it, when the backend exports traces to the run. */
     backend?: RunBackendSpan[];
+    /** The requests the app sent while it ran, with headers and bodies whose secrets are hidden. */
+    requests?: RequestRecord[];
+    /** What the app printed while it ran: its console, the errors it did not catch, its native log. */
+    logs?: RunLogLine[];
+};
+/** A printed line: `at` in ms since the epoch; `source` is `js`, `native` or `host`. */
+export type RunLogLine = {
+    at: number;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    source: string;
+    text: string;
+    stack?: string;
 };
 export type RunCase = {
     id: string;
     title?: string;
     description?: string;
+    /** What the case says about itself: why it matters, what is true when it starts, its ticket and expected outcome. */
+    about?: {
+        description?: string;
+        why?: string;
+        given?: string;
+        ticket?: string;
+        expected?: string;
+    };
     /** The case file, relative to where the run was started. */
     file: string;
     /** 1 for the first try; a case that failed and ran again has a line for each. */
@@ -99,9 +120,23 @@ export type RunManifest = {
     /** Whether the app ran on a device or simulator (true) or hosted without one. */
     native?: boolean;
     /** Where the run was made from, when it was a git checkout. */
+    /** `remote`: the repository's web address (no credentials); `changed`: files with changes no commit has (at most 20 of `changedCount`). */
+    /**
+     * `pushed`: what of it the remote has, as the clone knew when the run began (its remote-tracking refs, not a
+     * request): the branch, and the commit on any remote branch. A report links only what is there. A branch only this
+     * machine has is replaced by the remote branch that holds the commit, and `localBranch` keeps its name.
+     */
     git?: {
         branch?: string;
+        localBranch?: string;
         commit?: string;
+        remote?: string;
+        changed?: string[];
+        changedCount?: number;
+        pushed?: {
+            branch: boolean;
+            commit: boolean;
+        };
     };
     /** Cases by their last attempt. */
     totals?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkeus-protocol",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Wire contract between an app running lynkeus-agent and whatever drives it.",
   "type": "module",
   "main": "./lib/index.js",

package/src/fixtures.ts

@@ -0,0 +1,41 @@
+/**
+ * The fixtures protocol: how a case prepares and reads a backend through a server the project writes. lynkeus starts
+ * the command `cases.fixtures` names and speaks JSON lines to it, one request and one answer per line.
+ * The full contract is docs/FIXTURES.md.
+ */
+export const FIXTURES_PROTOCOL = 1;
+
+/** One step, as lynkeus sends it: `params` as the case wrote them, `env` the same flattened to upper-case strings. */
+export type FixtureRequest = { command: string; params: Record<string, unknown>; env: Record<string, string> };
+
+/** Any JSON object; `ok: false` with an `error` when the step failed. */
+export type FixtureAnswer = { ok?: boolean; error?: string } & Record<string, unknown>;
+
+/** A parameter a command takes, for authors and models choosing a setup. */
+export type FixtureParam = {
+  type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  summary?: string;
+  /** The values it takes, when they are few. */
+  values?: (string | number | boolean)[];
+  default?: unknown;
+  required?: boolean;
+};
+
+/** What a command does, for authors and models: what state it makes or reads, its parameters, one example. */
+export type FixtureCommand = {
+  name: string;
+  summary?: string;
+  params?: Record<string, FixtureParam>;
+  /** The params of one call that works, as a case would write them. */
+  example?: Record<string, unknown>;
+  /** What its answer carries that a later step reads (`user_id`, `api_key`…). */
+  answers?: string[];
+  /** `false` for a command that only reads: safe to call while checking a server. */
+  changes?: boolean;
+};
+
+/**
+ * The answer to `lynkeus.describe`. `commands` lists names, or descriptions, or both; a server from before
+ * descriptions answers names only, and that stays valid. `down` says the server runs but cannot serve.
+ */
+export type FixturesDescription = { protocol?: number; commands: (string | FixtureCommand)[]; down?: string };

package/src/index.ts

@@ -97,6 +97,11 @@ export type WaitForParams = {
   /** Swipe the nearest scrolling container towards the target until it is in the window. */
   scroll?: boolean;
   timeoutMs?: number;
+  /**
+   * A trace mark (`trace().last`): a `route` the app reached after it counts as arrived, even if the app has
+   * already left it. A screen that closes itself (a success screen) can come and go while a step's frame settles.
+   */
+  since?: number;
 };
 
 export type TraceEvent = { seq: number; t: number } & (
@@ -114,6 +119,9 @@ export type TraceEvent = { seq: number; t: number } & (
   | { kind: 'crash'; message: string; stack?: string; route?: string }
 );
 
+/** One side of a request: its headers and body, sensitive values replaced by `…`, a long body cut. */
+export type Exchange = { headers?: Record<string, string>; body?: string; truncated?: boolean };
+
 export type RequestRecord = {
   id: number;
   method: string;
@@ -122,6 +130,9 @@ export type RequestRecord = {
   startedAt: number;
   ms?: number;
   error?: string;
+  /** Only while a driver asked for bodies (`networkBodies`). */
+  request?: Exchange;
+  response?: Exchange;
 };
 
 /** Every method the core answers. Apps add their own through `qa.register`. */
@@ -151,7 +162,7 @@ export type CoreMethods = {
   back: { params: undefined; result: { route?: string } };
   waitFor: {
     params: WaitForParams;
-    result: { route?: string; matched?: Target; waitedMs: number };
+    result: { route?: string; matched?: Target; waitedMs: number /** The route was reached after `since` and left again. */; passed?: boolean };
   };
   idle: {
     /** `after`: a commit count from before the awaited change; quiet only counts once the app has committed past it. */
@@ -195,3 +206,4 @@ export type AuthEvent = { event: 'auth'; session: string; token?: string };
 export type AgentEvent = HelloEvent | NavigationEvent;
 
 export * from './run.js';
+export * from './fixtures.js';

package/src/run.ts

@@ -1,3 +1,4 @@
+import type { RequestRecord } from './index.js';
 /**
  * What a run of cases leaves behind: a directory anything can read without
  * knowing how the run was made.
@@ -67,12 +68,21 @@ export type RunStep = {
   videoS?: number;
   /** What the backend did for it, when the backend exports traces to the run. */
   backend?: RunBackendSpan[];
+  /** The requests the app sent while it ran, with headers and bodies whose secrets are hidden. */
+  requests?: RequestRecord[];
+  /** What the app printed while it ran: its console, the errors it did not catch, its native log. */
+  logs?: RunLogLine[];
 };
 
+/** A printed line: `at` in ms since the epoch; `source` is `js`, `native` or `host`. */
+export type RunLogLine = { at: number; level: 'debug' | 'info' | 'warn' | 'error'; source: string; text: string; stack?: string };
+
 export type RunCase = {
   id: string;
   title?: string;
   description?: string;
+  /** What the case says about itself: why it matters, what is true when it starts, its ticket and expected outcome. */
+  about?: { description?: string; why?: string; given?: string; ticket?: string; expected?: string };
   /** The case file, relative to where the run was started. */
   file: string;
   /** 1 for the first try; a case that failed and ran again has a line for each. */
@@ -102,7 +112,21 @@ export type RunManifest = {
   /** Whether the app ran on a device or simulator (true) or hosted without one. */
   native?: boolean;
   /** Where the run was made from, when it was a git checkout. */
-  git?: { branch?: string; commit?: string };
+  /** `remote`: the repository's web address (no credentials); `changed`: files with changes no commit has (at most 20 of `changedCount`). */
+  /**
+   * `pushed`: what of it the remote has, as the clone knew when the run began (its remote-tracking refs, not a
+   * request): the branch, and the commit on any remote branch. A report links only what is there. A branch only this
+   * machine has is replaced by the remote branch that holds the commit, and `localBranch` keeps its name.
+   */
+  git?: {
+    branch?: string;
+    localBranch?: string;
+    commit?: string;
+    remote?: string;
+    changed?: string[];
+    changedCount?: number;
+    pushed?: { branch: boolean; commit: boolean };
+  };
   /** Cases by their last attempt. */
   totals?: { cases: number; passed: number; failed: number; unsupported: number; retried: number };
 };