@piwitests/reporter 0.61.0 → 0.62.0

package/dist/internal/capture/attachments.d.ts

@@ -33,10 +33,33 @@ declare const ATTACHMENT_NAMES: {
 };
 /** Set of every internal attachment name — used to skip them when collecting user attachments. */
 declare const INTERNAL_ATTACHMENT_NAMES: ReadonlySet<string>;
+/** A name of `ATTACHMENT_NAMES`. */
+type AttachmentName = (typeof ATTACHMENT_NAMES)[keyof typeof ATTACHMENT_NAMES];
+/**
+ * The content type the capture fixtures write `piwi-aria-snapshot` with, and
+ * the only one the reporter reads it with. An attachment made from a browser
+ * server's `x-playwright-attachment` header has the content type `text/plain`.
+ */
+declare const ARIA_SNAPSHOT_CONTENT_TYPE = "text/plain; charset=utf-8";
+/** Whether `attachment` has the name `name` and the content type the capture fixtures write it with. */
+declare function isPiwiAttachment(attachment: {
+    name: string;
+    contentType?: string;
+}, name: AttachmentName): boolean;
+/**
+ * The last of `attachments` that `isPiwiAttachment` accepts for `name`. A
+ * reader of an attachment the fixtures write more than once
+ * (`piwi-browser-functions`, `piwi-css-rules`) goes through every match with
+ * `isPiwiAttachment` instead.
+ */
+declare function findPiwiAttachment<T extends {
+    name: string;
+    contentType?: string;
+}>(attachments: readonly T[] | undefined, name: AttachmentName): T | undefined;
 
 /** Annotation type that surfaces a locator-healing suggestion in the report/trace. */
 declare const LOCATOR_SUGGESTION_ANNOTATION: "piwi-locator-suggestion";
 /** Annotation type that surfaces a human-confirmed replacement locator in the report/trace. */
 declare const USER_PICK_ANNOTATION: "piwi-user-pick";
 
-export { ATTACHMENT_NAMES, INTERNAL_ATTACHMENT_NAMES, LOCATOR_SUGGESTION_ANNOTATION, USER_PICK_ANNOTATION };
+export { ARIA_SNAPSHOT_CONTENT_TYPE, ATTACHMENT_NAMES, type AttachmentName, INTERNAL_ATTACHMENT_NAMES, LOCATOR_SUGGESTION_ANNOTATION, USER_PICK_ANNOTATION, findPiwiAttachment, isPiwiAttachment };

package/dist/internal/capture/attachments.js

@@ -20,11 +20,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/internal/capture/attachments.ts
 var attachments_exports = {};
 __export(attachments_exports, {
+  ARIA_SNAPSHOT_CONTENT_TYPE: () => ARIA_SNAPSHOT_CONTENT_TYPE,
   ATTACHMENT_NAMES: () => ATTACHMENT_NAMES,
   FAILURE_SCREENSHOT_ATTACHMENT: () => FAILURE_SCREENSHOT_ATTACHMENT,
   INTERNAL_ATTACHMENT_NAMES: () => INTERNAL_ATTACHMENT_NAMES,
   LOCATOR_SUGGESTION_ANNOTATION: () => LOCATOR_SUGGESTION_ANNOTATION,
-  USER_PICK_ANNOTATION: () => USER_PICK_ANNOTATION
+  USER_PICK_ANNOTATION: () => USER_PICK_ANNOTATION,
+  findPiwiAttachment: () => findPiwiAttachment,
+  isPiwiAttachment: () => isPiwiAttachment
 });
 module.exports = __toCommonJS(attachments_exports);
 
@@ -57,13 +60,29 @@ var ATTACHMENT_NAMES = {
   pauses: "piwi-pauses"
 };
 var INTERNAL_ATTACHMENT_NAMES = new Set(Object.values(ATTACHMENT_NAMES));
+var ARIA_SNAPSHOT_CONTENT_TYPE = "text/plain; charset=utf-8";
+function contentTypeOf(name) {
+  return name === ATTACHMENT_NAMES.ariaSnapshot ? ARIA_SNAPSHOT_CONTENT_TYPE : "application/json";
+}
+function isPiwiAttachment(attachment, name) {
+  return attachment.name === name && attachment.contentType === contentTypeOf(name);
+}
+function findPiwiAttachment(attachments, name) {
+  for (let i = (attachments?.length ?? 0) - 1; i >= 0; i--) {
+    if (isPiwiAttachment(attachments[i], name)) return attachments[i];
+  }
+  return void 0;
+}
 var LOCATOR_SUGGESTION_ANNOTATION = ATTACHMENT_NAMES.locatorSuggestion;
 var USER_PICK_ANNOTATION = ATTACHMENT_NAMES.userPick;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ARIA_SNAPSHOT_CONTENT_TYPE,
   ATTACHMENT_NAMES,
   FAILURE_SCREENSHOT_ATTACHMENT,
   INTERNAL_ATTACHMENT_NAMES,
   LOCATOR_SUGGESTION_ANNOTATION,
-  USER_PICK_ANNOTATION
+  USER_PICK_ANNOTATION,
+  findPiwiAttachment,
+  isPiwiAttachment
 });

package/dist/internal/capture/capture-fixtures.d.ts

@@ -3,6 +3,7 @@ export { ProbeArg, ProbedAttrs, probeElementAttrs } from '@piwitests/picker-dom'
 import { PageInteraction } from '@piwitests/core/page-interaction';
 import { Page, TestInfo, TestType, Fixtures, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, Locator } from '@playwright/test';
 import { LocatorPageUse, ProcessRole, RoleCost } from '@piwitests/core/wire';
+import { RunIntent, IntentAnswer } from '@piwitests/core/run-channel';
 import { JsCoverageEntry } from '@piwitests/core/code-reach';
 
 /** A main-frame navigation, full or same-document: the page starts over. */
@@ -26,6 +27,23 @@ declare class LocatorPageLog {
     list(): LocatorPageUse[];
 }
 
+/**
+ * The pause bar's Pick a locator and Record here, started from outside the page (the editor's hub, for Piwi Picker):
+ * the bar takes an intent while it waits for its answer, and one handed to it while it is about to (its highlight
+ * still drawing) waits for it; while a pick or a recording runs, none is taken.
+ */
+declare class BarIntents {
+    private take;
+    private queued;
+    private busy;
+    /** Hand the bar an intent; false while it runs one, or holds one already. */
+    offer(intent: RunIntent): boolean;
+    /** The bar waits for its answer: settles with the next intent handed to it. */
+    wait(): Promise<RunIntent>;
+    /** The bar got its answer: it takes no intent until it waits again. */
+    answered(): void;
+}
+
 /**
  * Register this package's `dist/` directory as a boxed stack prefix — the list
  * Playwright filters its own frames with — so a wrapped action's step location
@@ -166,6 +184,12 @@ interface TestMetrics {
         loopDelayP99Ms: number;
         loopDelayMaxMs: number;
         heapUsedMb: number;
+        /**
+         * The heap right after the lowest full garbage collection V8 ran during
+         * the test, or null when it ran none: what the worker really holds, without
+         * the garbage `heapUsedMb` counts until it is collected.
+         */
+        heapAfterGcMb?: number | null;
         /** Open file descriptors at the test's end (Linux). */
         fds: number | null;
     };
@@ -177,13 +201,19 @@ interface PageMain {
     /** Main-thread CPU since Piwi first read the page. */
     cpuMs: number;
     heapMb: number;
+    /** DOM nodes alive in the renderer, detached ones not yet collected included. */
     nodes: number;
     listeners: number;
+    /** Elements attached to the main frame's document: exact, with no garbage in it. */
+    elements?: number;
 }
 declare class WorkerMetrics {
     private readonly proc;
     private readonly pid;
     private readonly histogram;
+    private readonly gcObserver;
+    /** The lowest heap read right after a full garbage collection in the current window. */
+    private heapAfterGc;
     private readonly linux;
     private loop;
     private usage;
@@ -191,6 +221,11 @@ declare class WorkerMetrics {
     private subtree;
     private roles;
     constructor(proc?: ProcFs, pid?: number, platform?: NodeJS.Platform);
+    /**
+     * Read the heap after each full (major) garbage collection V8 runs on its
+     * own: nothing is forced, so a test that triggers none reads null.
+     */
+    private observeFullCollections;
     /** The worker's processes under it, keyed by pid and start time. */
     private tree;
     /**
@@ -218,6 +253,12 @@ declare class WorkerMetrics {
 declare class PageReader {
     private readonly sessions;
     read(page: object): Promise<PageMain | null>;
+    /**
+     * The elements attached to the page's main document, through the page's own
+     * DevTools session: no Playwright call, so no step and no trace action. The
+     * count runs in the page's main world and changes nothing in it.
+     */
+    private countElements;
 }
 
 /**
@@ -324,7 +365,24 @@ interface ResourceCensus {
     };
     /** Objects the test opened itself and left open (what `PIWI_LEAK_CHECK` judges). */
     leftOpen?: number;
+    /**
+     * The servers and child processes the test started (its body, its
+     * each-hooks or a test-scoped fixture) and left running in the worker, with
+     * the line that started each. Present when the ledger tracks them; the
+     * `handles` counts then leave servers out.
+     */
+    running?: RunningHandle[];
 }
+/** A server or a child process a test left running in the worker. */
+interface RunningHandle {
+    type: NodeHandleType;
+    /** The line that started it, `file:line`. */
+    site: string | null;
+    /** A child process: the program it runs, without its arguments. */
+    command?: string;
+}
+/** The Node handles the ledger tracks one by one, by Node's own type names. */
+type NodeHandleType = 'TCPServerWrap' | 'ChildProcess';
 /** An object a test opened itself and left open: what `PIWI_LEAK_CHECK` fails or closes. */
 interface LeakedResource {
     id: number;
@@ -379,6 +437,8 @@ declare class ResourceLedger {
     private readonly testInfoSource;
     private readonly now;
     private readonly readers;
+    /** Track the servers and child processes the worker starts, by wrapping Node's `listen` and `spawn`. */
+    private readonly nodeHandles;
     private nextId;
     private readonly entries;
     private readonly byObject;
@@ -395,14 +455,39 @@ declare class ResourceLedger {
     private listener;
     /** A browser or a context was opened in this worker: there are browser processes for the metrics to read. */
     private sawBrowser;
+    /** The servers and child processes still running, while the ledger tracks them. */
+    private readonly handles;
+    private readonly byHandle;
+    private trackingHandles;
+    private readonly restores;
     constructor(playwright: PlaywrightLike, workerIndex: number, leakCheck?: LeakCheck, resultsFile?: string | null, testInfoSource?: () => TestInfoLike | null, now?: () => number, readers?: {
         metrics?: WorkerMetrics | null;
         pages?: PageReader | null;
-    });
+    }, 
+    /** Track the servers and child processes the worker starts, by wrapping Node's `listen` and `spawn`. */
+    nodeHandles?: boolean);
     /** Listen to the worker's Playwright and wrap its browser types. False when the instrumentation is missing. */
     install(): boolean;
-    /** Stop listening; the objects already tracked stay in the ledger. */
+    /** Stop listening, and put Node's `listen` and `spawn` back; the objects already tracked stay in the ledger. */
     uninstall(): void;
+    /**
+     * Wrap `net.Server.prototype.listen` (every HTTP, HTTPS and TCP server) and
+     * `ChildProcess.prototype.spawn` (`spawn`, `exec`, `execFile` and `fork`), so
+     * each server and child process the worker starts carries the line and the
+     * runnable that started it, as a context does. A worker-scoped fixture's
+     * server is then the worker's, never the first test's. Each wrapper calls the
+     * original on its receiver and only records; it never throws.
+     */
+    private wrapNodeHandles;
+    private trackHandle;
+    private onServer;
+    private onChild;
+    /**
+     * The servers and child processes a test started (its body, its each-hooks
+     * or a test-scoped fixture) that still run. A server whose `listen` has not
+     * bound yet is read again one tick later.
+     */
+    private runningOf;
     /** Mark a page used: a locator was built on it. */
     notePageUse(page: object): void;
     /** Open the census window of a test. */
@@ -420,6 +505,8 @@ declare class ResourceLedger {
     private readPages;
     /** The census a worker takes as it shuts down, appended to the results file when the reporter set one. */
     workerEnded(): ResourceCensus;
+    /** The handle types counted at each boundary: servers leave the count once they are tracked one by one. */
+    private countedHandleTypes;
     private guard;
     private wrapBrowserType;
     private track;
@@ -582,6 +669,26 @@ declare function ariaSnapshotBestEffort(target: Locator, timeout?: number): Prom
  * yields null and the capture proceeds with the YAML alone.
  */
 declare function ariaSnapshotJSONBestEffort(target: Locator, timeout?: number): Promise<string | null>;
+/** What a stop the bar shows says to an intent: whether it can record, whether its page is a guess, whether it holds. */
+interface IntentStop {
+    record: boolean;
+    guessed: boolean;
+    /** Neither answered nor ending: its test goes on, and neither its page nor its context began to close. */
+    holds(): boolean;
+}
+/**
+ * Start an intent from outside the page, at a stop the bar shows: answered at once, the pick, the recording, the
+ * check or the region's pick then running in the test's window as from the bar, and ending with the stop. Refused at
+ * a stop that is over or ending, and at one whose page is a guess (`StopPage`), which the person outside the page
+ * cannot see.
+ */
+declare function intentAt(intents: BarIntents, what: RunIntent, stop: IntentStop): IntentAnswer;
+/**
+ * A failure's error as its stop names it to the editor, as plain text: the failing error's message without its ANSI
+ * codes and without the `Error: ` the runner writes before a plain error's message, its lines up to the first blank
+ * one or its call log, four at most and `MAX_STOP_ERROR` characters; null for an error with no text.
+ */
+declare function failureError(message: string | undefined): string | null;
 /**
  * The fixtures `piwiFixtures` / `extendPiwiFixtures` contribute. The single
  * added fixture is `piwiCapture`: an auto, test-scoped teardown hook that
@@ -597,11 +704,12 @@ interface PiwiFixtures {
  * The worker fixture `piwiFixtures` / `extendPiwiFixtures` contribute:
  * `piwiResources`, an auto, worker-scoped fixture that keeps the worker's
  * resource ledger (the browsers, contexts, pages and API request contexts its
- * tests open) from before the first hook to the worker's shutdown, and records
+ * tests open) from before the first hook to the worker's shutdown, records
  * the calls tests make through the API request contexts `playwright.request`
- * creates, the `request` fixture's among them. Its name is **reserved** like
+ * creates, the `request` fixture's among them, and holds the worker's run
+ * connection to the editor that started the run. Its name is **reserved** like
  * `piwiCapture`'s: a fixture of your own with that name replaces it and turns
- * the ledger and those calls' capture off.
+ * the ledger, those calls' capture and the run connection off.
  */
 interface PiwiWorkerFixtures {
     piwiResources: void;
@@ -637,4 +745,4 @@ declare const piwiFixtures: Fixtures<PiwiFixtures, PiwiWorkerFixtures, Playwrigh
  */
 declare function extendPiwiFixtures<TestArgs extends FixtureArgs, WorkerArgs extends FixtureArgs>(test: TestType<TestArgs, WorkerArgs>): TestType<TestArgs & PiwiFixtures, WorkerArgs & PiwiWorkerFixtures>;
 
-export { CAPTURED_ATTRS_ARG, LocatorPageLog, type PageState, type PiwiFixtures, type PiwiWorkerFixtures, type RawPageState, type RawVitalEntry, activeResourceLedger, ariaSnapshotBestEffort, ariaSnapshotJSONBestEffort, boxCaptureFrames, buildPageState, callMethod, codeReachRoots, computeCoreVitals, configuredCodeReachRoots, extendPiwiFixtures, internalCall, noteLocatorCall, noteNavigation, noteResourceUse, pageMapFetcher, piwiFixtures, readPageInteraction, recordResourceCensus, resolveCodeReach, startCodeReach, startResourceLedger, stopCodeReach, stopResourceLedger };
+export { CAPTURED_ATTRS_ARG, type IntentStop, LocatorPageLog, type PageState, type PiwiFixtures, type PiwiWorkerFixtures, type RawPageState, type RawVitalEntry, activeResourceLedger, ariaSnapshotBestEffort, ariaSnapshotJSONBestEffort, boxCaptureFrames, buildPageState, callMethod, codeReachRoots, computeCoreVitals, configuredCodeReachRoots, extendPiwiFixtures, failureError, intentAt, internalCall, noteLocatorCall, noteNavigation, noteResourceUse, pageMapFetcher, piwiFixtures, readPageInteraction, recordResourceCensus, resolveCodeReach, startCodeReach, startResourceLedger, stopCodeReach, stopResourceLedger };