@piwitests/reporter 0.67.0 → 0.69.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -31,6 +31,7 @@ declare const ATTACHMENT_NAMES: {
31
31
  readonly aiMeta: "piwi-ai-meta";
32
32
  readonly resources: "piwi-resources";
33
33
  readonly pauses: "piwi-pauses";
34
+ readonly environment: "piwi-environment";
34
35
  };
35
36
  /** Set of every internal attachment name — used to skip them when collecting user attachments. */
36
37
  declare const INTERNAL_ATTACHMENT_NAMES: ReadonlySet<string>;
@@ -58,7 +58,8 @@ var ATTACHMENT_NAMES = {
58
58
  aiUsage: "piwi-ai-usage",
59
59
  aiMeta: "piwi-ai-meta",
60
60
  resources: "piwi-resources",
61
- pauses: "piwi-pauses"
61
+ pauses: "piwi-pauses",
62
+ environment: "piwi-environment"
62
63
  };
63
64
  var INTERNAL_ATTACHMENT_NAMES = new Set(Object.values(ATTACHMENT_NAMES));
64
65
  var ARIA_SNAPSHOT_CONTENT_TYPE = "text/plain; charset=utf-8";
@@ -82,6 +82,55 @@ declare class LocatorPageLog {
82
82
  list(): LocatorPageUse[];
83
83
  }
84
84
 
85
+ /**
86
+ * The run page's live view on the team instance. While a run of a project that turned it on executes, each worker
87
+ * keeps one event stream open to the instance, with a key for that run alone that the reporter sets in the workers'
88
+ * environment (`PIWI_LIVE_VIEW`, `<url>#<key>`, `formatLiveViewEnv`). On that stream the instance says how many people
89
+ * watch the worker (`viewers`), and which elements its project masks (`masks`). While anyone does, the worker posts small JPEG frames of its test's page, each with the
90
+ * call it was taken at and the title of its test, a few a second at most, and the instance relays them to those viewers
91
+ * alone and keeps none.
92
+ * The worker also posts when its test stops and goes on (`stop`), which the run page shows, when the test watched
93
+ * ended (`ended`), and when the run stops being shared (`unshared`). In a CI run, while anyone watches it in full, it
94
+ * posts too the call its test is in as Playwright logs it (`call-log`): the log's last lines, the point an input action acts on,
95
+ * and the elements the call's locator matches while it waits. Nothing goes from the instance to the page: the
96
+ * view never steers the run. Each message is JSON, checked field by field (`parseInstanceToWorker`,
97
+ * `readWorkerToInstance`).
98
+ *
99
+ * An instance that says on the stream what its viewers ask of the images (`view`: the largest size they show one at,
100
+ * in device pixels, the pace, and whether one of them shows the worker in full) takes each frame as its JPEG's bytes
101
+ * behind a short JSON header, one live message (`LIVE_FRAME_TYPE`); an older instance takes the frame in base64 inside
102
+ * JSON. The call log and the test's end go only to a full view: a worker that only tiles show posts neither, and
103
+ * follows no call log. A viewer reads one stream of live
104
+ * messages (`LIVE_STREAM_TYPE`): the frames of the workers it watches, their images as bytes, and the JSON messages
105
+ * of the view (`LiveViewerMessage`). A live message is a length-prefixed JSON header, then length-prefixed bytes
106
+ * (`encodeLiveMessage`, `createLiveMessageReader`): the dashboard and any other viewer read it with this one reader.
107
+ *
108
+ * Beside the images, a viewer of the worker in full may ask for the layers of `@piwitests/core/live-layers`
109
+ * (`LiveWatchAsk`'s `layers` on the instance): the instance says which on the worker's stream (`view`'s `layers`, the
110
+ * union of what its full views ask), and the worker posts them while asked alone, each naming its test: what the page
111
+ * and the test's requests said (`page-event`), the page's text (`text`, as the instance asks for it, `text` on the
112
+ * stream), and the images of its test's filmstrip (`thumb`, a live message whose data is the JPEG: the view's own masked
113
+ * images, kept in the worker's memory for a viewer who comes later, sent again on `resend`). The instance relays each to
114
+ * the watches that asked for that layer, and keeps none.
115
+ *
116
+ * A full view may also ask for **Inspect** (`view`'s `inspect`): the worker then posts the DOM snapshots its page's
117
+ * trace takes at each call (`snapshot`) and the resources they name (`resource`), as `@piwitests/core/live-inspect`
118
+ * says, and the instance tells each watch with Inspect open of each snapshot (`snapshot`, its data left out), which it
119
+ * serves rendered on its own.
120
+ *
121
+ * A CI run's workers open their streams at once. A run outside CI holds its key too, and its workers open no stream
122
+ * until a person shares the run (**Share live**, the run channel's `share`), and close it as the sharing stops. Such a
123
+ * run without a key names why instead (`none:<why>`, `formatLiveViewMissing`), for the surfaces to say.
124
+ */
125
+
126
+ /** A call of the test, as the run page names it: its title and its place in the user's code, when known. */
127
+ interface LiveCall {
128
+ title: string;
129
+ /** The file, relative to the run's working directory, with forward slashes. */
130
+ file: string | null;
131
+ line: number | null;
132
+ }
133
+
85
134
  /**
86
135
  * The run channel: each worker of a test run the editor started keeps one connection, from before its first test to its
87
136
  * end, to the local socket the editor service listens on for the record channel's hand-offs
@@ -93,7 +142,11 @@ declare class LocatorPageLog {
93
142
  * element** and a region's ARIA snapshot, started from outside the page; at any stop, the responses the test kept (an
94
143
  * interactive run keeps the text bodies of its pages' fetch and XHR answers), one of them to mock, and a locator's
95
144
  * matches; and, for a viewer outside the page, the stopped page's live view (`@piwitests/core/run-view`: its frames,
96
- * the input played on it) and the locator of the element under a point of an image of it; and, for an agent (the
145
+ * the input played on it) and the locator of the element under a point of an image of it; for a viewer of the
146
+ * worker's lane, its running test's page live, through its tests and stops (`view-lane`, a feature beyond `takes`),
147
+ * and the layers of that view its viewers ask beside the images (`layers`, `lane-layer`: `@piwitests/core/live-layers`);
148
+ * for the hub alone, where its running attempt's trace grows (`trace`), which the hub opens in Playwright's trace
149
+ * viewer and names to no one; and, for an agent (the
97
150
  * editor's MCP server), the stopped page's ARIA snapshot in AI mode, an action on one of its elements by its ref, that
98
151
  * element's ranked locators, what the run does as it goes (`events`), and its browser bound for Playwright's own tools
99
152
  * on request (`bind`). A worker holds a failure for the editor only once the service said it shows and answers one
@@ -112,6 +165,11 @@ declare class LocatorPageLog {
112
165
  * (`region`).
113
166
  */
114
167
  type RunIntent = 'pick' | 'record' | 'assert' | 'assert-region';
168
+ /**
169
+ * The actions in the test's window that take Escape as their own, which a worker says run (`acting`): a pick, a check
170
+ * and a region's pick end on it. A recording does not: it records Escape as a step of the test.
171
+ */
172
+ type RunActing = Exclude<RunIntent, 'record'>;
115
173
  /** Whether an intent started, or why not, in one sentence. */
116
174
  interface IntentAnswer {
117
175
  ok: boolean;
@@ -121,12 +179,18 @@ interface IntentAnswer {
121
179
  /**
122
180
  * The pause bar's Pick a locator and Record here, started from outside the page (the editor's hub, for Piwi Picker):
123
181
  * the bar takes an intent while it waits for its answer, and one handed to it while it is about to (its highlight
124
- * still drawing) waits for it; while a pick or a recording runs, none is taken.
182
+ * still drawing) waits for it; while a pick or a recording runs, none is taken. Each action in the test's window that
183
+ * takes Escape as its own (a pick, a check, a region's pick: `RunActing`), the bar's own or an intent, is said to `said`
184
+ * as it starts, and null once it ended (`acting`); a recording, which records Escape as a step, is not.
125
185
  */
126
186
  declare class BarIntents {
127
187
  private take;
128
188
  private queued;
129
189
  private busy;
190
+ private readonly said;
191
+ constructor(said?: (what: RunActing | null) => void);
192
+ /** Runs an action in the test's window (`what`), saying it runs until it ended. */
193
+ acting<T>(what: RunActing, run: () => Promise<T>): Promise<T>;
130
194
  /** Hand the bar an intent; false while it runs one, or holds one already. */
131
195
  offer(intent: RunIntent): boolean;
132
196
  /** The bar waits for its answer: settles with the next intent handed to it. */
@@ -135,14 +199,6 @@ declare class BarIntents {
135
199
  answered(): void;
136
200
  }
137
201
 
138
- /** A call of the test, as the run page names it: its title and its place in the user's code, when known. */
139
- interface LiveCall {
140
- title: string;
141
- /** The file, relative to the run's working directory, with forward slashes. */
142
- file: string | null;
143
- line: number | null;
144
- }
145
-
146
202
  /**
147
203
  * Register this package's `dist/` directory as a boxed stack prefix — the list
148
204
  * Playwright filters its own frames with — so a wrapped action's step location
@@ -183,8 +239,8 @@ declare function internalCall<T>(owner: unknown, run: () => Promise<T>): Promise
183
239
  * At line granularity, V8's block coverage tells which code ran inside a
184
240
  * function: at each offset, the innermost range around it (a function or a
185
241
  * block) gives its count. A source line is executable when a source map
186
- * segment maps to it, and it ran when one of those segments starts at an
187
- * offset that ran. A script with no map counts the lines holding code inside
242
+ * segment holding code maps to it, and it ran when one of those segments ran
243
+ * at its first character of code ({@link scriptLines}). A script with no map counts the lines holding code inside
188
244
  * the functions V8 lists, its top level left out, and one of them ran when
189
245
  * code on it ran.
190
246
  *
@@ -431,6 +487,19 @@ interface ResourceTestRef {
431
487
  /** Set on the test a census closes when it failed: Playwright shuts its worker down right after it. */
432
488
  failed?: boolean;
433
489
  }
490
+ /** The last call a test made on an object, or on anything under it (a page's frames and elements, a context's pages). */
491
+ interface ResourceUse {
492
+ at: number;
493
+ /** The line that made it, `file:line`. */
494
+ site: string | null;
495
+ /** The test that made it. */
496
+ test?: string;
497
+ }
498
+ /** The fixture being set up or torn down: its title, and its location for a fixture of the suite's own. */
499
+ interface ResourceFixture {
500
+ title: string;
501
+ location: string | null;
502
+ }
434
503
  interface ResourceBirth {
435
504
  id: number;
436
505
  kind: ResourceKind;
@@ -438,12 +507,16 @@ interface ResourceBirth {
438
507
  parent: number | null;
439
508
  at: number;
440
509
  phase: ResourcePhase;
441
- /** The fixture being set up when the object was opened; `worker` when that fixture is worker-scoped. */
442
- fixture: {
443
- title: string;
444
- location: string | null;
510
+ /**
511
+ * The fixture being set up when the object was opened. `worker` when it ran
512
+ * with a timeout slot, which Playwright gives a worker-scoped fixture and any
513
+ * fixture with a `timeout` of its own; `timed` for the second case, whose
514
+ * scope the slot does not tell.
515
+ */
516
+ fixture: (ResourceFixture & {
445
517
  worker: boolean;
446
- } | null;
518
+ timed?: boolean;
519
+ }) | null;
447
520
  /** The test it was opened during; for a `beforeAll`, the test that ran the hook. */
448
521
  test: ResourceTestRef | null;
449
522
  /** The line that opened it, `file:line`. */
@@ -452,7 +525,7 @@ interface ResourceBirth {
452
525
  opener?: number;
453
526
  /** A popup: the call that was running or last ran when it appeared. */
454
527
  trigger?: string;
455
- /** A context `browser.newPage()` opened for its page. */
528
+ /** A context `browser.newPage()` opened for its page, or the browser `launchPersistentContext` opened for its context. */
456
529
  implicit?: boolean;
457
530
  /** A context Playwright reuses across tests on purpose (UI mode, `--reuse-context`). */
458
531
  reused?: boolean;
@@ -462,8 +535,18 @@ interface ResourceClose {
462
535
  at: number;
463
536
  phase: ResourcePhase;
464
537
  test: ResourceTestRef | null;
538
+ /** The fixture tearing down when it closed. */
539
+ fixture?: ResourceFixture;
465
540
  /** Pages: whether anything ever ran on it. */
466
541
  used?: boolean;
542
+ /** The last call a test made on it before it closed. */
543
+ lastUse?: ResourceUse;
544
+ /**
545
+ * When its close began, or its context's or browser's: before the work a
546
+ * close does first (Piwi's reads of its pages, Playwright saving its trace).
547
+ * Set when it began before `at`.
548
+ */
549
+ closingAt?: number;
467
550
  /** Closed by `PIWI_LEAK_CHECK=close`. */
468
551
  byPiwi?: boolean;
469
552
  }
@@ -473,7 +556,9 @@ interface ResourceOpen {
473
556
  used?: boolean;
474
557
  /** Pages: the current URL, without query or hash. */
475
558
  url?: string;
476
- /** Pages: listeners on Playwright's page events. */
559
+ /** The last call a test made on it so far. */
560
+ lastUse?: ResourceUse;
561
+ /** Listeners on Playwright's events of the page, the context or the browser. */
477
562
  listeners?: number;
478
563
  /** Pages and contexts: `route()` handlers. */
479
564
  routes?: number;
@@ -491,6 +576,8 @@ interface ResourceCensus {
491
576
  at: number;
492
577
  /** The test this census closes; null for the census a worker takes as it shuts down. */
493
578
  test: ResourceTestRef | null;
579
+ /** When the test this census closes started, before its test-scoped fixtures were set up. */
580
+ startedAt?: number;
494
581
  born: ResourceBirth[];
495
582
  closed: ResourceClose[];
496
583
  open: ResourceOpen[];
@@ -536,14 +623,21 @@ interface LeakedResource {
536
623
  implicit: boolean;
537
624
  /** A popup: the call that opened it. */
538
625
  trigger?: string;
626
+ /** The line of the last call the test made on it, where its close belongs. */
627
+ lastUse?: string | null;
539
628
  }
540
629
  interface Instrumentation {
541
630
  addListener?: (listener: object) => void;
542
631
  removeListener?: (listener: object) => void;
543
632
  }
633
+ /** A connection to Playwright (internal): every call of the objects it carries goes through it. */
634
+ interface ConnectionLike {
635
+ sendMessageToServer?: (object: unknown, method: unknown, params: unknown, options: unknown) => unknown;
636
+ }
544
637
  type BrowserTypeLike = Record<string, unknown>;
545
638
  interface PlaywrightLike {
546
639
  _instrumentation?: Instrumentation;
640
+ _connection?: ConnectionLike;
547
641
  chromium?: BrowserTypeLike;
548
642
  firefox?: BrowserTypeLike;
549
643
  webkit?: BrowserTypeLike;
@@ -556,6 +650,9 @@ interface TestInfoLike {
556
650
  titlePath?: string[];
557
651
  status?: string;
558
652
  expectedStatus?: string;
653
+ project?: {
654
+ timeout?: number;
655
+ };
559
656
  _timeoutManager?: {
560
657
  _running?: {
561
658
  runnable?: {
@@ -566,7 +663,9 @@ interface TestInfoLike {
566
663
  file?: string;
567
664
  line?: number;
568
665
  };
569
- slot?: unknown;
666
+ slot?: {
667
+ timeout?: number;
668
+ } | null;
570
669
  };
571
670
  };
572
671
  } | null;
@@ -589,6 +688,14 @@ declare class ResourceLedger {
589
688
  private lastCall;
590
689
  /** The page a wrapped page method is calling into: its first reported API call marks it used. */
591
690
  private usingPage;
691
+ /**
692
+ * The connections the ledger follows, each with what puts it back: every call a test makes through one marks what
693
+ * it lands on used.
694
+ */
695
+ private readonly followed;
696
+ /** The client-side waits a test began, by their id, with the object each waits on and the line that began it. */
697
+ private readonly waits;
698
+ private windowStartedAt;
592
699
  private born;
593
700
  private closed;
594
701
  private handlesAtStart;
@@ -611,6 +718,39 @@ declare class ResourceLedger {
611
718
  nodeHandles?: boolean);
612
719
  /** Listen to the worker's Playwright and wrap its browser types. False when the instrumentation is missing. */
613
720
  install(): boolean;
721
+ /**
722
+ * Follow every call made through a connection to Playwright
723
+ * (`sendMessageToServer`, internal): the worker's own, and that of each
724
+ * browser it connects to. A call a test made (with its frames, not
725
+ * `internal` like Piwi's own reads and Playwright's artifacts) marks the
726
+ * object it lands on used, and the page, context and browser it belongs to
727
+ * (its `_parent` chain), with when and from which line. A long call (an
728
+ * assertion, a wait on the browser) keeps it in use until it returns, and a
729
+ * wait on the client (`waitForEvent` and its kin) until its internal end. A
730
+ * close marks when the object's close began; a `route()` handler's answers to
731
+ * the page's own traffic are no use. The pages of a connection it does not
732
+ * follow keep being marked used by their page methods and locators.
733
+ */
734
+ private followCalls;
735
+ /** Stop following a connection, and let it go: a browser the worker connected to and has left. */
736
+ private unfollow;
737
+ /** Whether the ledger follows the calls of an object's connection. */
738
+ private follows;
739
+ private onCall;
740
+ /**
741
+ * A wait on the client begins with a call of the test's (with its frames)
742
+ * and ends with an internal one of the same id: the object it waited on was
743
+ * in use until then.
744
+ */
745
+ private onWait;
746
+ /**
747
+ * Mark an object, and the page, context and browser it belongs to, used now
748
+ * by the call at `site`. A close that began before it did not end: the
749
+ * object is in use again.
750
+ */
751
+ private touch;
752
+ /** Mark when an object's close began, the first time it begins. */
753
+ noteClosing(object: object): void;
614
754
  /** Stop listening, and put Node's `listen` and `spawn` back; the objects already tracked stay in the ledger. */
615
755
  uninstall(): void;
616
756
  /**
@@ -658,6 +798,8 @@ declare class ResourceLedger {
658
798
  /** `initial` is set for a page that came with its context (a persistent context's), which is no popup. */
659
799
  private onPage;
660
800
  private onClosed;
801
+ /** When the close of an object, or of the context or browser it belongs to, began first; null when none did. */
802
+ private closingOf;
661
803
  private latestPendingCall;
662
804
  private openEntries;
663
805
  /**
@@ -668,6 +810,7 @@ declare class ResourceLedger {
668
810
  private leaksOf;
669
811
  /** Open pages under a context, or under any context of a browser. */
670
812
  private pagesUnder;
813
+ /** A context `browser.newPage()` opened for its page, or a browser `launchPersistentContext` opened for its context. */
671
814
  private isImplicit;
672
815
  private openPagesOf;
673
816
  private closeLeaks;
@@ -844,6 +987,18 @@ type CodePlace = {
844
987
  * as Windows writes them. Null for an error with no such frame (a test timeout).
845
988
  */
846
989
  declare function errorPlace(error: unknown, windows?: boolean): CodePlace | null;
990
+ /**
991
+ * Whether the runner traces the attempt, as its tracing's options say once the attempt began (`_tracing.traceOptions()`,
992
+ * Playwright internal: the options, with their `mode`, for a traced attempt, none for another); null on a runner of
993
+ * another shape.
994
+ */
995
+ declare function runnerTraces(testInfo: TestInfo): boolean | null;
996
+ /**
997
+ * Whether the runner's trace of the attempt takes DOM snapshots, as its tracing's options say (Playwright internal,
998
+ * feature-checked): `snapshots`, or its `dom` where it names each kind (1.64, `{ aria: true }` taking none); null where
999
+ * it does not trace the attempt or its shape is not known.
1000
+ */
1001
+ declare function runnerTraceSnapshots(testInfo: TestInfo): boolean | null;
847
1002
  /**
848
1003
  * The call the test is on, as the run page's live view names it beside each frame, its file relative to the working
849
1004
  * directory. Null for none.
@@ -905,4 +1060,4 @@ declare const piwiFixtures: Fixtures<PiwiFixtures, PiwiWorkerFixtures, Playwrigh
905
1060
  */
906
1061
  declare function extendPiwiFixtures<TestArgs extends FixtureArgs, WorkerArgs extends FixtureArgs>(test: TestType<TestArgs, WorkerArgs>): TestType<TestArgs & PiwiFixtures, WorkerArgs & PiwiWorkerFixtures>;
907
1062
 
908
- export { CAPTURED_ATTRS_ARG, type IntentStop, LocatorPageLog, type PageState, type PiwiFixtures, type PiwiWorkerFixtures, ProbeArg, ProbedAttrs, type RawPageState, type RawVitalEntry, activeResourceLedger, ariaSnapshotBestEffort, ariaSnapshotJSONBestEffort, boxCaptureFrames, buildPageState, callMethod, codeReachRoots, computeCoreVitals, configuredCodeReachRoots, errorPlace, extendPiwiFixtures, failureError, intentAt, internalCall, noteLocatorCall, noteNavigation, noteResourceUse, pageMapFetcher, piwiFixtures, probeElementAttrs, readPageInteraction, recordResourceCensus, resolveCodeReach, runningCall, startCodeReach, startResourceLedger, stopCodeReach, stopResourceLedger };
1063
+ export { CAPTURED_ATTRS_ARG, type IntentStop, LocatorPageLog, type PageState, type PiwiFixtures, type PiwiWorkerFixtures, ProbeArg, ProbedAttrs, type RawPageState, type RawVitalEntry, activeResourceLedger, ariaSnapshotBestEffort, ariaSnapshotJSONBestEffort, boxCaptureFrames, buildPageState, callMethod, codeReachRoots, computeCoreVitals, configuredCodeReachRoots, errorPlace, extendPiwiFixtures, failureError, intentAt, internalCall, noteLocatorCall, noteNavigation, noteResourceUse, pageMapFetcher, piwiFixtures, probeElementAttrs, readPageInteraction, recordResourceCensus, resolveCodeReach, runnerTraceSnapshots, runnerTraces, runningCall, startCodeReach, startResourceLedger, stopCodeReach, stopResourceLedger };