@piwitests/reporter 0.68.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.
@@ -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
@@ -94,8 +143,10 @@ declare class LocatorPageLog {
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
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
97
- * worker's lane, its running test's page live, through its tests and stops (`view-lane`, a feature beyond `takes`);
98
- * and, for an agent (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
99
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
100
151
  * element's ranked locators, what the run does as it goes (`events`), and its browser bound for Playwright's own tools
101
152
  * on request (`bind`). A worker holds a failure for the editor only once the service said it shows and answers one
@@ -114,6 +165,11 @@ declare class LocatorPageLog {
114
165
  * (`region`).
115
166
  */
116
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'>;
117
173
  /** Whether an intent started, or why not, in one sentence. */
118
174
  interface IntentAnswer {
119
175
  ok: boolean;
@@ -123,12 +179,18 @@ interface IntentAnswer {
123
179
  /**
124
180
  * The pause bar's Pick a locator and Record here, started from outside the page (the editor's hub, for Piwi Picker):
125
181
  * the bar takes an intent while it waits for its answer, and one handed to it while it is about to (its highlight
126
- * 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.
127
185
  */
128
186
  declare class BarIntents {
129
187
  private take;
130
188
  private queued;
131
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>;
132
194
  /** Hand the bar an intent; false while it runs one, or holds one already. */
133
195
  offer(intent: RunIntent): boolean;
134
196
  /** The bar waits for its answer: settles with the next intent handed to it. */
@@ -137,14 +199,6 @@ declare class BarIntents {
137
199
  answered(): void;
138
200
  }
139
201
 
140
- /** A call of the test, as the run page names it: its title and its place in the user's code, when known. */
141
- interface LiveCall {
142
- title: string;
143
- /** The file, relative to the run's working directory, with forward slashes. */
144
- file: string | null;
145
- line: number | null;
146
- }
147
-
148
202
  /**
149
203
  * Register this package's `dist/` directory as a boxed stack prefix — the list
150
204
  * Playwright filters its own frames with — so a wrapped action's step location
@@ -933,6 +987,18 @@ type CodePlace = {
933
987
  * as Windows writes them. Null for an error with no such frame (a test timeout).
934
988
  */
935
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;
936
1002
  /**
937
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
938
1004
  * directory. Null for none.
@@ -994,4 +1060,4 @@ declare const piwiFixtures: Fixtures<PiwiFixtures, PiwiWorkerFixtures, Playwrigh
994
1060
  */
995
1061
  declare function extendPiwiFixtures<TestArgs extends FixtureArgs, WorkerArgs extends FixtureArgs>(test: TestType<TestArgs, WorkerArgs>): TestType<TestArgs & PiwiFixtures, WorkerArgs & PiwiWorkerFixtures>;
996
1062
 
997
- 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 };