@piwitests/reporter 0.44.0 → 0.46.0

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

@@ -21,6 +21,7 @@ declare const ATTACHMENT_NAMES: {
     readonly userPick: "piwi-user-pick";
     readonly aiUsage: "piwi-ai-usage";
     readonly aiMeta: "piwi-ai-meta";
+    readonly resources: "piwi-resources";
 };
 /** Set of every internal attachment name — used to skip them when collecting user attachments. */
 declare const INTERNAL_ATTACHMENT_NAMES: ReadonlySet<string>;

package/dist/internal/capture/attachments.js

@@ -41,7 +41,8 @@ var ATTACHMENT_NAMES = {
   pageState: "piwi-page-state",
   userPick: "piwi-user-pick",
   aiUsage: "piwi-ai-usage",
-  aiMeta: "piwi-ai-meta"
+  aiMeta: "piwi-ai-meta",
+  resources: "piwi-resources"
 };
 var INTERNAL_ATTACHMENT_NAMES = new Set(Object.values(ATTACHMENT_NAMES));
 var LOCATOR_SUGGESTION_ANNOTATION = ATTACHMENT_NAMES.locatorSuggestion;

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

@@ -1,7 +1,7 @@
 import { ProbeArg } from '@piwitests/picker-dom';
 export { ProbeArg, ProbedAttrs, probeElementAttrs } from '@piwitests/picker-dom';
-import { Page, TestType, Fixtures, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, Locator } from '@playwright/test';
-import { LocatorPageUse } from '@piwitests/core/wire';
+import { Page, TestInfo, TestType, Fixtures, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, Locator } from '@playwright/test';
+import { LocatorPageUse, ProcessRole, RoleCost } from '@piwitests/core/wire';
 import { JsCoverageEntry } from '@piwitests/core/code-reach';
 
 /** A main-frame navigation, full or same-document: the page starts over. */
@@ -66,6 +66,364 @@ declare function startCodeReach(page: Page): Promise<boolean>;
 /** Stop JavaScript coverage and return its entries; null when it cannot be read. */
 declare function stopCodeReach(page: Page): Promise<JsCoverageEntry[] | null>;
 
+interface ProcStat {
+    pid: number;
+    ppid: number;
+    comm: string;
+    /** User plus system CPU time. */
+    cpuMs: number;
+    /** Start time in clock ticks since boot: with the pid, it names one process even when the pid is reused. */
+    start: number;
+}
+/** CPU ticks of the whole machine, from the first line of `/proc/stat`. */
+interface CpuTicks {
+    busy: number;
+    idle: number;
+    iowait: number;
+    steal: number;
+    total: number;
+}
+/** Linux's `/proc`, under a root a test can replace. */
+declare class ProcFs {
+    readonly root: string;
+    constructor(root?: string);
+    /** Whether this looks like a Linux `/proc` at all. */
+    available(): boolean;
+    /** Every process, keyed by pid. */
+    table(): Map<number, ProcStat>;
+    stat(pid: number): ProcStat | null;
+    runWaitMs(pid: number): number | null;
+    cmdline(pid: number): string;
+    /** A field of `/proc/<pid>/status`, in kB: `VmRSS`, `VmHWM`. */
+    statusKb(pid: number, key: string): number | null;
+    /** Proportional set size: shared pages split between the processes sharing them, so a sum counts them once. */
+    pssKb(pid: number): Promise<number | null>;
+    /** Reset a process's peak RSS (`VmHWM`) to its current RSS. */
+    resetPeakRss(pid: number): boolean;
+    cpuTicks(): CpuTicks | null;
+    /** Total stall time of a resource's pressure file, in µs. */
+    pressureUs(resource: 'cpu' | 'memory' | 'io'): number | null;
+    memAvailableKb(): number | null;
+    /** Open file descriptors of a process. */
+    fdCount(pid: number): number | null;
+}
+
+/**
+ * What a test cost its worker, read at the test's start and end: the worker
+ * process's own CPU and health (event loop, involuntary context switches,
+ * heap), and on Linux the processes it started — its browsers — by role, with
+ * their CPU, the time they waited for a CPU and their peak memory during the
+ * test. Plus, over the Chrome DevTools Protocol, the main-thread CPU and weight
+ * of the pages that outlive their test. Every read is best-effort.
+ */
+interface TestMetrics {
+    worker: {
+        cpuMs: number;
+        involuntarySwitches: number;
+        /** Share of the test's time the event loop was busy. */
+        loopUtilization: number;
+        loopDelayP99Ms: number;
+        loopDelayMaxMs: number;
+        heapUsedMb: number;
+        /** Open file descriptors at the test's end (Linux). */
+        fds: number | null;
+    };
+    /** The processes the worker started, by role (Linux). */
+    roles?: Partial<Record<ProcessRole, RoleCost>>;
+}
+/** A page's main thread and weight, over CDP (Chromium). */
+interface PageMain {
+    /** Main-thread CPU since Piwi first read the page. */
+    cpuMs: number;
+    heapMb: number;
+    nodes: number;
+    listeners: number;
+}
+declare class WorkerMetrics {
+    private readonly proc;
+    private readonly pid;
+    private readonly histogram;
+    private readonly linux;
+    private loop;
+    private usage;
+    /** Each process's CPU and wait at the start of the current window; null before the first. */
+    private subtree;
+    private roles;
+    constructor(proc?: ProcFs, pid?: number, platform?: NodeJS.Platform);
+    /** The worker's processes under it, keyed by pid and start time. */
+    private tree;
+    /**
+     * The processes under the worker now, and the reset of their peak memory: the
+     * start of the next window. Taken once per test, at its end, so the time
+     * between two tests counts toward the next one.
+     */
+    private snapshot;
+    /**
+     * Start a test's window. `processes` says whether the worker has started any
+     * browser to read; a worker that never did skips the process tree.
+     */
+    start(processes?: boolean): void;
+    /** Close the window. Null when the test's start was never read. */
+    end(processes?: boolean): TestMetrics | null;
+    /** The window's cost by role; what it reads becomes the start of the next window. */
+    private roleCosts;
+    dispose(): void;
+}
+/**
+ * Reads pages over CDP, one session per page, opened the first time a page is
+ * read and kept while it lives. On a browser without CDP the read is null, and
+ * the page is never tried again.
+ */
+declare class PageReader {
+    private readonly sessions;
+    read(page: object): Promise<PageMain | null>;
+}
+
+/**
+ * The resource ledger: every browser, context, page and API request context a
+ * worker opens, where it was opened, whether anything ran on it, and when it
+ * closed. One per worker process, started by the `piwiResources` worker fixture
+ * before any hook runs. At the end of each test the capture fixture takes a
+ * census — what was born and closed since the last one, and what is open now —
+ * and attaches it as `piwi-resources`; the reporter turns the censuses into
+ * findings (`internal/collect/resource-verdicts.ts`). It never throws into a
+ * test, and every Playwright internal it reads is feature-detected.
+ */
+type ResourceKind = 'browser' | 'context' | 'page' | 'request';
+/** What the capture fixtures do with an object a test left open: list it, fail the test, or close it. */
+type LeakCheck = 'report' | 'fail' | 'close';
+/** The kind of code Playwright was running when an object was opened or closed. */
+type ResourcePhase = 'test' | 'beforeEach' | 'afterEach' | 'beforeAll' | 'afterAll' | 'worker';
+/** A test, as a census and the objects it saw name it. */
+interface ResourceTestRef {
+    id: string;
+    /** Spec file relative to the working directory, POSIX separators. */
+    file: string;
+    /** The describe blocks between the file and the test. */
+    suite: string[];
+    /** Set on the test a census closes. */
+    title?: string;
+    /** Set on the test a census closes when it failed: Playwright shuts its worker down right after it. */
+    failed?: boolean;
+}
+interface ResourceBirth {
+    id: number;
+    kind: ResourceKind;
+    /** The context of a page, the browser of a context. */
+    parent: number | null;
+    at: number;
+    phase: ResourcePhase;
+    /** The fixture being set up when the object was opened; `worker` when that fixture is worker-scoped. */
+    fixture: {
+        title: string;
+        location: string | null;
+        worker: boolean;
+    } | null;
+    /** The test it was opened during; for a `beforeAll`, the test that ran the hook. */
+    test: ResourceTestRef | null;
+    /** The line that opened it, `file:line`. */
+    site: string | null;
+    /** A popup: the page that opened it. */
+    opener?: number;
+    /** A popup: the call that was running or last ran when it appeared. */
+    trigger?: string;
+    /** A context `browser.newPage()` opened for its page. */
+    implicit?: boolean;
+    /** A context Playwright reuses across tests on purpose (UI mode, `--reuse-context`). */
+    reused?: boolean;
+}
+interface ResourceClose {
+    id: number;
+    at: number;
+    phase: ResourcePhase;
+    test: ResourceTestRef | null;
+    /** Pages: whether anything ever ran on it. */
+    used?: boolean;
+    /** Closed by `PIWI_LEAK_CHECK=close`. */
+    byPiwi?: boolean;
+}
+interface ResourceOpen {
+    id: number;
+    /** Pages: whether anything ran on it so far. */
+    used?: boolean;
+    /** Pages: the current URL, without query or hash. */
+    url?: string;
+    /** Pages: listeners on Playwright's page events. */
+    listeners?: number;
+    /** Pages and contexts: `route()` handlers. */
+    routes?: number;
+    /** Contexts: open pages. */
+    pages?: number;
+    /** Pages, over CDP: main-thread CPU and weight. */
+    main?: PageMain;
+}
+/** One census: what changed since the previous one in this worker, and what is open now. */
+interface ResourceCensus {
+    v: 1;
+    /** Playwright's worker index and the worker's process id. */
+    worker: number;
+    pid: number;
+    at: number;
+    /** The test this census closes; null for the census a worker takes as it shuts down. */
+    test: ResourceTestRef | null;
+    born: ResourceBirth[];
+    closed: ResourceClose[];
+    open: ResourceOpen[];
+    /** Counts of the tracked Node handle types in the worker at the test's start and end. */
+    handles?: {
+        start: Record<string, number>;
+        end: Record<string, number>;
+    };
+    /** What the test cost the worker and the browsers it started. */
+    metrics?: TestMetrics;
+    /** Contexts and pages already open in the worker when the test started. */
+    openAtStart?: {
+        contexts: number;
+        pages: number;
+    };
+    /** Objects the test opened itself and left open (what `PIWI_LEAK_CHECK` judges). */
+    leftOpen?: number;
+}
+/** An object a test opened itself and left open: what `PIWI_LEAK_CHECK` fails or closes. */
+interface LeakedResource {
+    id: number;
+    kind: ResourceKind;
+    site: string | null;
+    /** Contexts and browsers: how many open pages go with it. */
+    pages: number;
+    implicit: boolean;
+    /** A popup: the call that opened it. */
+    trigger?: string;
+}
+interface Instrumentation {
+    addListener?: (listener: object) => void;
+    removeListener?: (listener: object) => void;
+}
+type BrowserTypeLike = Record<string, unknown>;
+interface PlaywrightLike {
+    _instrumentation?: Instrumentation;
+    chromium?: BrowserTypeLike;
+    firefox?: BrowserTypeLike;
+    webkit?: BrowserTypeLike;
+}
+/** The parts of Playwright's worker `TestInfo` the ledger reads (`_timeoutManager` is internal). */
+interface TestInfoLike {
+    testId?: string;
+    title?: string;
+    file?: string;
+    titlePath?: string[];
+    status?: string;
+    expectedStatus?: string;
+    _timeoutManager?: {
+        _running?: {
+            runnable?: {
+                type?: string;
+                fixture?: {
+                    title?: string;
+                    location?: {
+                        file?: string;
+                        line?: number;
+                    };
+                    slot?: unknown;
+                };
+            };
+        } | null;
+    };
+}
+declare class ResourceLedger {
+    private readonly playwright;
+    readonly workerIndex: number;
+    readonly leakCheck: LeakCheck;
+    private readonly resultsFile;
+    private readonly testInfoSource;
+    private readonly now;
+    private readonly readers;
+    private nextId;
+    private readonly entries;
+    private readonly byObject;
+    private readonly pendingCalls;
+    private lastCall;
+    /** The page a wrapped page method is calling into: its first reported API call marks it used. */
+    private usingPage;
+    private born;
+    private closed;
+    private handlesAtStart;
+    private openAtStart;
+    /** The test between `testStarted` and `testEnded`, for when Playwright's own test info cannot be read. */
+    private window;
+    private listener;
+    /** A browser or a context was opened in this worker: there are browser processes for the metrics to read. */
+    private sawBrowser;
+    constructor(playwright: PlaywrightLike, workerIndex: number, leakCheck?: LeakCheck, resultsFile?: string | null, testInfoSource?: () => TestInfoLike | null, now?: () => number, readers?: {
+        metrics?: WorkerMetrics | null;
+        pages?: PageReader | null;
+    });
+    /** 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. */
+    uninstall(): void;
+    /** Mark a page used: a locator was built on it. */
+    notePageUse(page: object): void;
+    /** Open the census window of a test. */
+    testStarted(info: TestInfoLike): void;
+    /**
+     * Close the census window of a test: apply `PIWI_LEAK_CHECK=close` to what the
+     * test left open, then take the census. Called after the test-scoped fixtures
+     * tore down, so what the test opened through them is closed by now.
+     */
+    testEnded(info: TestInfoLike): Promise<{
+        census: ResourceCensus;
+        leaks: LeakedResource[];
+    }>;
+    /** The open pages' main thread and weight, over CDP, within a deadline. */
+    private readPages;
+    /** The census a worker takes as it shuts down, appended to the results file when the reporter set one. */
+    workerEnded(): ResourceCensus;
+    private guard;
+    private wrapBrowserType;
+    private track;
+    private onBrowser;
+    private onContext;
+    /** `initial` is set for a page that came with its context (a persistent context's), which is no popup. */
+    private onPage;
+    private onClosed;
+    private latestPendingCall;
+    private openEntries;
+    /**
+     * Objects a test opened itself, by its body or its each-hooks, and left open.
+     * A page in a leaked context, or a context in a leaked browser, goes with it;
+     * the context `browser.newPage()` opened for its page goes with the page.
+     */
+    private leaksOf;
+    /** Open pages under a context, or under any context of a browser. */
+    private pagesUnder;
+    private isImplicit;
+    private openPagesOf;
+    private closeLeaks;
+    private census;
+    private pageUrl;
+    private listenerCount;
+    private routeCount;
+}
+/**
+ * Start this worker's ledger on the Playwright the worker fixtures hold, unless
+ * `PIWI_CAPTURE_RESOURCES=false` or that Playwright has no instrumentation to
+ * listen to. Starting it again returns the running one.
+ */
+declare function startResourceLedger(playwright: unknown, workerIndex: number): ResourceLedger | null;
+/** This worker's running ledger, if any. */
+declare function activeResourceLedger(): ResourceLedger | null;
+/** Take the shutdown census of this worker's ledger and stop it. */
+declare function stopResourceLedger(): ResourceCensus | null;
+/** Mark a page used, for the locator wrappers. */
+declare function noteResourceUse(page: object): void;
+/**
+ * Take the census at the end of a test, attach it as `piwi-resources`, and fail
+ * the test under `PIWI_LEAK_CHECK=fail` when it left open what it opened. A
+ * no-op when no ledger runs in this worker.
+ */
+declare function recordResourceCensus(testInfo: TestInfo): Promise<void>;
+
 type FixtureArgs = {
     [key: string]: any;
 };
@@ -184,6 +542,17 @@ declare function callMethod(target: object, prop: string | symbol, args: unknown
 interface PiwiFixtures {
     piwiCapture: void;
 }
+/**
+ * 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. Its name is
+ * **reserved** like `piwiCapture`'s: a fixture of your own with that name
+ * replaces it and turns the ledger off.
+ */
+interface PiwiWorkerFixtures {
+    piwiResources: void;
+}
 /**
  * Playwright fixtures that collect network requests, console entries,
  * web vitals, ARIA snapshots, and locator interaction data during a test.
@@ -193,7 +562,7 @@ interface PiwiFixtures {
  * `browser.newContext()`. Collected data is attached as `piwi-*`
  * test-info attachments which the Piwi Dashboard reporter parses on `onTestEnd`.
  */
-declare const piwiFixtures: Fixtures<PiwiFixtures, {}, PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
+declare const piwiFixtures: Fixtures<PiwiFixtures, PiwiWorkerFixtures, PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
 /**
  * Extend a Playwright `test` object with the Piwi capture fixtures. The
  * returned `test` carries the existing fixtures plus {@link PiwiFixtures}.
@@ -210,6 +579,6 @@ declare const piwiFixtures: Fixtures<PiwiFixtures, {}, PlaywrightTestArgs & Play
  * export const test = extendPiwiFixtures(base);
  * ```
  */
-declare function extendPiwiFixtures<TestArgs extends FixtureArgs, WorkerArgs extends FixtureArgs>(test: TestType<TestArgs, WorkerArgs>): TestType<TestArgs & PiwiFixtures, WorkerArgs>;
+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 RawPageState, type RawVitalEntry, ariaSnapshotBestEffort, ariaSnapshotJSONBestEffort, boxCaptureFrames, buildPageState, callMethod, codeReachRoots, computeCoreVitals, configuredCodeReachRoots, extendPiwiFixtures, internalCall, noteLocatorCall, noteNavigation, pageMapFetcher, piwiFixtures, resolveCodeReach, startCodeReach, stopCodeReach };
+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, recordResourceCensus, resolveCodeReach, startCodeReach, startResourceLedger, stopCodeReach, stopResourceLedger };