lynkeus 0.3.0 → 0.5.0

package/lib/cases/runfile.js

@@ -14,8 +14,19 @@ export const toRunCase = (c, { report, attempt, startedAt }, root, dir) => {
         // The runner numbers an event's step from 1, in the order the steps ran.
         const told = (report.events ?? [])
             .filter((e) => e.step === index + 1)
-            .map((e) => ({ origin: 'app', name: e.name, ...(e.props ? { props: e.props } : {}), ...(e.route ? { route: e.route } : {}) }));
-        const sent = (s.sent ?? []).map((e) => ({ origin: 'app', provider: e.provider, name: e.name, ...(e.props ? { props: e.props } : {}) }));
+            .map((e) => ({
+            origin: 'app',
+            ...(e.provider ? { provider: e.provider } : {}),
+            name: e.name,
+            ...(e.props ? { props: e.props } : {}),
+            ...(e.route ? { route: e.route } : {}),
+        }));
+        const sent = (s.sent ?? []).map((e) => ({
+            origin: e.via === 'server' ? 'server' : 'app',
+            provider: e.provider,
+            name: e.name,
+            ...(e.props ? { props: e.props } : {}),
+        }));
         const events = [...told, ...sent];
         const screenshot = within(dir, s.screenshot);
         return {
@@ -28,6 +39,8 @@ export const toRunCase = (c, { report, attempt, startedAt }, root, dir) => {
             ...(screenshot ? { screenshot } : {}),
             ...(s.videoS !== undefined ? { videoS: s.videoS } : {}),
             ...(s.backend?.length ? { backend: s.backend } : {}),
+            ...(s.requests?.length ? { requests: s.requests } : {}),
+            ...(s.logs?.length ? { logs: s.logs } : {}),
         };
     });
     const description = typeof c.meta.description === 'string' ? c.meta.description : undefined;
@@ -36,6 +49,7 @@ export const toRunCase = (c, { report, attempt, startedAt }, root, dir) => {
         id: report.id,
         ...(report.title ? { title: report.title } : {}),
         ...(description ? { description } : {}),
+        ...(report.about ? { about: report.about } : {}),
         file: path.relative(root, path.resolve(root, report.file)),
         attempt,
         result: report.result,
@@ -48,7 +62,7 @@ export const toRunCase = (c, { report, attempt, startedAt }, root, dir) => {
     };
 };
 /** The branch and commit the run was made from, so a report can say which code it tested. */
-const gitOf = (root) => {
+export const gitOf = (root) => {
     const ask = (...args) => {
         try {
             return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
@@ -61,7 +75,56 @@ const gitOf = (root) => {
     if (!commit)
         return undefined;
     const branch = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || ask('rev-parse', '--abbrev-ref', 'HEAD');
-    return { commit, ...(branch && branch !== 'HEAD' ? { branch } : {}) };
+    const remote = webOf(ask('remote', 'get-url', 'origin'));
+    // What the run had that no commit has: a report says the app was not exactly the commit it names.
+    const changed = (ask('status', '--porcelain', '--untracked-files=no') ?? '')
+        .split('\n')
+        .map((l) => l.slice(3).trim())
+        .filter(Boolean);
+    // A branch that lives only on this machine names nothing a reader can open: the run names the remote branch
+    // that has its commit instead (the one it tracks first, else any), and keeps the local name beside it.
+    const local = branch && branch !== 'HEAD' ? branch : undefined;
+    const onRemote = (name) => !!ask('rev-parse', '--verify', '--quiet', `refs/remotes/origin/${name}`);
+    const holding = remote && local && !onRemote(local) ? remoteBranchWith(ask, commit) : undefined;
+    const shown = holding ?? local;
+    const pushed = remote ? { branch: !!shown && (shown === holding || onRemote(shown)), commit: !!ask('branch', '--remotes', '--contains', commit) } : undefined;
+    return {
+        commit,
+        ...(shown ? { branch: shown } : {}),
+        ...(holding && local ? { localBranch: local } : {}),
+        ...(remote ? { remote } : {}),
+        ...(pushed ? { pushed } : {}),
+        ...(changed.length ? { changed: changed.slice(0, 20), changedCount: changed.length } : {}),
+    };
+};
+/** The origin branch that holds `commit`: the one the checkout tracks when it does, else the first. */
+const remoteBranchWith = (ask, commit) => {
+    const strip = (ref) => ref.replace(/^origin\//, '');
+    const upstream = ask('rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}');
+    const holders = (ask('branch', '--remotes', '--contains', commit, '--format=%(refname:short)') ?? '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.startsWith('origin/') && l !== 'origin/HEAD' && l !== 'origin');
+    if (upstream && holders.includes(upstream))
+        return strip(upstream);
+    return holders[0] ? strip(holders[0]) : undefined;
+};
+/** A remote as a web address a report can link commits to, without any credentials it carried. */
+export const webOf = (url) => {
+    if (!url)
+        return undefined;
+    const ssh = url.match(/^[\w.-]+@([\w.-]+):(.+?)(\.git)?$/);
+    if (ssh)
+        return `https://${ssh[1]}/${ssh[2]}`;
+    try {
+        const u = new URL(url);
+        if (u.protocol !== 'https:' && u.protocol !== 'http:' && u.protocol !== 'ssh:')
+            return undefined;
+        return `https://${u.hostname}${u.pathname.replace(/\.git$/, '')}`;
+    }
+    catch {
+        return undefined;
+    }
 };
 export class RunFile {
     dir;

package/lib/cases/runner.d.ts

@@ -1,3 +1,4 @@
+import type { RequestRecord } from 'lynkeus-protocol';
 import { type AppEvent, type RunEvent } from '../knowledge/events.js';
 import { type Base, type Command } from '../registry.js';
 import type { Fixtures, FixturesConfig } from './fixtures.js';
@@ -34,6 +35,8 @@ export type CasesConfig = {
     /** `{ "user": "user_id" }` turns `user: u` into `user_id: <u.user_id>`, and gives a step that names no user the latest one. */
     refs?: Record<string, string>;
     /** Steps this project adds: `{ "app.login": [...] }`. Inside, `{{param.x}}` is what the case passed. */
+    /** The screen a case begins on, for drafts (`case new`): the first the app shows a signed-in person, say. */
+    start?: string;
     macros?: Record<string, unknown[]>;
     /** What the app may put in the way of a step and the steps that get past it; a step whose own words match `unless` is about it, and is left alone. */
     interruptions?: {
@@ -41,12 +44,27 @@ export type CasesConfig = {
         do: unknown[];
         unless?: string;
     }[];
+    /**
+     * What the backend told its own analytics while a step ran, for a report: after each app step the fixture is
+     * asked with `{ since }` (the step's start, ISO) and answers `{ events: [{ name | event, props | payload,
+     * provider? }] }`. `provider` names the service when the fixture does not (an Olympus that sends to Mixpanel).
+     */
+    serverEvents?: {
+        fixture: string;
+        provider?: string;
+    };
+    /** The service the app's own event list feeds (its `events` command), so a report names it instead of "App". */
+    appEvents?: {
+        provider: string;
+    };
 };
 /** What a host's analytics capture saw a step send: the SDK it went to and the event. */
+/** `via`: the SDK's native module (a host that stands in for it), the request it sent, or the backend's own analytics. */
 export type SentEvent = {
     provider: string;
     name: string;
     props?: Record<string, unknown>;
+    via?: 'sdk' | 'network' | 'server';
 };
 /** `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 = {
@@ -62,6 +80,18 @@ export type StepReport = {
     sent?: SentEvent[];
     /** What the backend did for it, from the traces it exported to the run. */
     backend?: BackendSpan[];
+    /** The requests the app sent while it ran, with headers and bodies (secrets hidden), when the run keeps evidence. */
+    requests?: RequestRecord[];
+    /** What the app printed while it ran: its console and the errors it did not catch, when the run keeps evidence. */
+    logs?: LogLine[];
+};
+/** A line the app printed: `at` in ms since the epoch, `source` where it came from (`js`, `native`, `host`). */
+export type LogLine = {
+    at: number;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    source: string;
+    text: string;
+    stack?: string;
 };
 export type CaseReport = {
     id: string;
@@ -71,6 +101,17 @@ export type CaseReport = {
     result: 'passed' | 'failed' | 'unsupported';
     ms: number;
     steps: StepReport[];
+    /**
+     * What a reader needs before the steps: what the case proves (`description`), why it matters (`why`), what
+     * has to be true when it starts (`given`), the ticket it covers and the outcome it expects. From its frontmatter.
+     */
+    about?: {
+        description?: string;
+        why?: string;
+        given?: string;
+        ticket?: string;
+        expected?: string;
+    };
     /** When a step failed: the screen, the requests since the mark, and why. */
     evidence?: {
         screen?: string;
@@ -87,11 +128,20 @@ export type CaseReport = {
     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. */
+/** `frames`: AVIF where the host writes it (a fifth of a PNG's bytes, lossy), or PNG, exact, for frames two runs are compared by. */
 export type Evidence = {
     dir: string;
     screenshots?: boolean;
+    settleMs?: number;
+    /** Wait for the screen to stand still: two frames alike this many ms apart, on a host's own clock where it offers
+     * that (`still`), or taken again on a device. */
+    stillMs?: number;
+    /** A looking step on an unchanged screen shares the last frame instead of taking one. */
+    onChange?: boolean;
+    frames?: 'avif' | 'png';
     video?: {
         fps: number;
+        scale?: number;
     };
 };
 export type RunOptions = {
@@ -113,7 +163,10 @@ export type RunOptions = {
     /** 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';
+    routes?: boolean | 'fresh' /** The app's native log on a simulator or an emulator, read step by step into each step's logs. */;
+    nativeLogs?: {
+        take: () => LogLine[];
+    };
 };
 /** What a case's setup leaves for its steps: the aliases and what they answered, and what ran. */
 export type Prepared = {
@@ -135,4 +188,8 @@ export declare const argvFor: (command: Command, value: StepValue) => string[];
 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 fileRequestsByTrace: (steps: StepReport[], spans: Map<string, {
+    index: number;
+    startedMs: number;
+}>) => void;
 export declare const runCase: (c: Case, options: RunOptions) => Promise<CaseReport>;