@piwitests/reporter 0.66.0 → 0.68.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.
package/dist/index.d.ts CHANGED
@@ -61,6 +61,13 @@ interface PiwiDashboardOptions {
61
61
  collectScmInfo?: boolean;
62
62
  /** Auto-collect CI environment info. Defaults to `true`. */
63
63
  collectCiInfo?: boolean;
64
+ /**
65
+ * Record where the run executed: the runner's time zone, locale, OS, Node.js version and CI image, each browser as
66
+ * its page reports itself (with the capture fixtures), and each instrumented server under test. The dashboard
67
+ * shows when they change between runs or shards. Defaults to `true`. Can also be forced off with
68
+ * `PIWI_COLLECT_ENVIRONMENT_INFO=false`.
69
+ */
70
+ collectEnvironmentInfo?: boolean;
64
71
  /** Collect step timings, network requests and web vitals. Defaults to `true`. */
65
72
  collectPerformanceMetrics?: boolean;
66
73
  /**
@@ -256,16 +263,20 @@ interface PiwiDashboardOptions {
256
263
  * `trace` options on the top-level `use` block so a failing test keeps a
257
264
  * screenshot (`'only-on-failure'`) and a trace (`'retain-on-failure'`) even
258
265
  * without the capture fixtures — the trace alone unlocks the DOM snapshot,
259
- * full call stack, full network with bodies and the visual diff. On Playwright
260
- * 1.63 or later the trace default also turns on the per-action aria tree
261
- * (`snapshots: { dom: true, aria: true }`), which adds the accessibility tree
262
- * before and after each action at negligible size. The `screen` snapshot kind
263
- * (a PNG per action, the trace's biggest cost) stays opt-in — set it yourself
264
- * with `use: { trace: { mode: 'retain-on-failure', snapshots: { dom: true,
265
- * aria: true, screen: true } } }`. Only fills options the config leaves unset;
266
- * an explicit value (including `'off'`) and per-project `use` blocks are never
267
- * touched. Defaults to `true`. Set to `false` (or `PIWI_DEFAULT_CAPTURE=false`)
268
- * to opt out and let Playwright's own defaults stand.
266
+ * full call stack, full network with bodies and the visual diff. The trace
267
+ * records DOM snapshots, not ARIA snapshots. To record those too (Playwright
268
+ * 1.63+), for the in-execution page diff and the accessibility tree at the
269
+ * failing action, set the trace yourself: `use: { trace: { mode: 'retain-on-failure',
270
+ * snapshots: { dom: true, aria: true } } }`. They cost run time on every
271
+ * attempt, passing ones included: Playwright waits for up to three ARIA
272
+ * snapshots per input action, each hundreds of milliseconds on a large page
273
+ * (ten clicks on a 1,000-row table took 8,967 ms with them against 1,021 ms
274
+ * without, on Playwright 1.64.1 and Chromium). Add `screen: true` for a PNG
275
+ * per action, the trace's biggest storage cost. Only fills options the config
276
+ * leaves unset; an explicit value (including `'off'`) and per-project `use`
277
+ * blocks are never touched. Defaults to `true`. Set to `false` (or
278
+ * `PIWI_DEFAULT_CAPTURE=false`) to opt out and let Playwright's own defaults
279
+ * stand.
269
280
  */
270
281
  defaultCapture?: boolean;
271
282
  /**
@@ -488,8 +499,8 @@ declare function createGlobalSetup(options?: PiwiDashboardOptions, userSetup?: (
488
499
  *
489
500
  * The top-level `use` block's `screenshot` and `trace` are defaulted to
490
501
  * `'only-on-failure'` / `'retain-on-failure'` when unset so failure evidence is
491
- * captured without the fixtures; on Playwright 1.63 or later `trace` also turns
492
- * on the per-action aria tree (`snapshots: { dom: true, aria: true }`). An
502
+ * captured without the fixtures; the trace records DOM snapshots, not ARIA
503
+ * snapshots (set `trace` yourself to record them, see `defaultCapture`). An
493
504
  * explicit value (including `'off'`) is kept. Opt out with `defaultCapture:
494
505
  * false` (or `PIWI_DEFAULT_CAPTURE=false`).
495
506
  *
@@ -529,10 +540,21 @@ declare class PiwiDashboardReporter {
529
540
  private plannedTests;
530
541
  /** Ids of tests that actually reported via `onTestEnd`, to find the ones that never ran. */
531
542
  private reportedTestIds;
532
- /** The spec files said to have run without the capture fixtures in a run that can stop (`noteUncaptured`). */
543
+ /**
544
+ * The spec files said to have run without the capture fixtures in a run that can stop, or whose workers stream to
545
+ * the instance's live view (`noteUncaptured`).
546
+ */
533
547
  private uncapturedSpecs;
548
+ /** Whether the run is a CI run whose workers stream to the instance's live view, set in `onBegin`. */
549
+ private liveViewOn;
550
+ /** The run's own connection to the hub its workers reach, from `onBegin` to `onEnd`; null for a run without one. */
551
+ private hubLink;
534
552
  /** The live steps begun and not ended, by step, sent again when someone opens the run (`onWatched`). */
535
553
  private openSteps;
554
+ /** The attempts running now, by test id, for the stops their workers note (`heardStop`). */
555
+ private runningTests;
556
+ /** Reads the stops the workers note (`readStopNotes`). */
557
+ private stopNotes;
536
558
  /**
537
559
  * The failed attempts with retries left, by `test.id`: each is its test's last failure when no later attempt has a
538
560
  * say in its outcome (`decidesOutcome`), the run stopping before the retry or the retry not running.
@@ -559,8 +581,12 @@ declare class PiwiDashboardReporter {
559
581
  * finalizing a run would create an empty phantom run and upload an empty report.
560
582
  */
561
583
  private readonly listMode;
584
+ /** True under `playwright merge-reports`, which replays blob reports: no test runs and nothing of the run is live. */
585
+ private readonly mergingReports;
562
586
  /** True when the server URL and API key came from the desktop app, not from config. */
563
587
  private viaDesktopApp;
588
+ /** The team instance a requested run uploads to, or why it uploads nowhere. */
589
+ private requestedRun;
564
590
  /** The configured server `desktopApp: 'prefer'` set aside for the desktop app, if any. */
565
591
  private readonly desktopReplaced;
566
592
  /** The config folder's `.env` file and the connection variables taken from it, if any. */
@@ -577,6 +603,8 @@ declare class PiwiDashboardReporter {
577
603
  private resourceCensuses;
578
604
  /** Lifecycle steps of the tests that ran without the fixtures. */
579
605
  private lifecycleTallies;
606
+ /** The spec and helper files those steps point at, read once each. */
607
+ private readonly sourceLines;
580
608
  /** The user fixtures set up by the tests that left a page unused, by test id. */
581
609
  private fixturesByTest;
582
610
  /** The file workers append their shutdown census to, set in `onBegin`. */
@@ -597,6 +625,8 @@ declare class PiwiDashboardReporter {
597
625
  private lastTestWatch;
598
626
  /** The manifests of the instrumented origins the run reaches beyond its base URLs. */
599
627
  private manifests;
628
+ /** Where the run executes: the runner, each project's browser and each server under test; null when off. */
629
+ private environments;
600
630
  /** Result events that stream once their test's server coverage is in. */
601
631
  private coverageSends;
602
632
  /** The errors Playwright reported outside any test (`onError`), the first `MAX_RUN_ERRORS` of them. */
@@ -627,16 +657,29 @@ declare class PiwiDashboardReporter {
627
657
  * environment: the key the instance gave the global setup, for a project that turned its live view on, for this run
628
658
  * alone. A CI run's workers stream with it at once; a run outside CI's hold it until a person shares the run (Share
629
659
  * live), and such a run without a key names why instead, for the surfaces that would share it; a CI run without one
630
- * says why in its log (`ciLiveViewNote`). Read before the stream starts, which takes the setup file.
660
+ * says why in its log (`ciLiveViewNote`). Read before the stream starts, which takes the setup file. A run that
661
+ * merges blob reports starts no worker and is not live: it says nothing of the live view.
631
662
  */
632
663
  private shareLiveView;
664
+ /** Why the run holds no live view key, from what its global setup left (`setup`, its registration, if any). */
665
+ private liveViewMissing;
633
666
  /**
634
667
  * Settle each planned test's external ID before any test runs, name the IDs two tests share, and record them on
635
668
  * the run so the dashboard lists them too.
636
669
  */
637
670
  private planExternalIds;
671
+ /**
672
+ * Name the planned tests whose tags are cut at the limit, once, and record them on the run so the dashboard shows
673
+ * them too. A planned test whose properties cannot be read is left out.
674
+ */
675
+ private noteTagsTruncated;
638
676
  /** The external ID fields of a test's payload: `null` tells the dashboard the test has none to match on. */
639
677
  private externalIdFields;
678
+ /**
679
+ * A stop a worker noted (`stop-notes.ts`), of an attempt running now: a `test-stopped` event as it shows and a
680
+ * `test-resumed` as it ends, named as its `begin` named the attempt, sent whoever watches.
681
+ */
682
+ private heardStop;
640
683
  /** Playwright reporter hook: called when an individual test begins */
641
684
  onTestBegin(test: TestCase, result: TestResult): void;
642
685
  /**
@@ -655,21 +698,31 @@ declare class PiwiDashboardReporter {
655
698
  /** Step categories streamed live while the run executes. */
656
699
  private static readonly LIVE_STEP_CATEGORIES;
657
700
  /**
658
- * Whether a step streams live: its category is in `LIVE_STEP_CATEGORIES`
659
- * and no ancestor is an `expect` step. The steps inside an assertion are its
660
- * polling — every `expect.poll` attempt and `toPass` retry — not a step a
661
- * human watches; the meaningful readout is the assertion around them.
701
+ * Whether a step streams live: its category is in `LIVE_STEP_CATEGORIES`,
702
+ * no ancestor is an `expect` step, and neither it nor an ancestor is Piwi's
703
+ * own (`isCaptureStep`: its fixtures, its attachments, its page reads). The
704
+ * steps inside an assertion are its polling — every `expect.poll` attempt and
705
+ * `toPass` retry — not a step a human watches; the meaningful readout is the
706
+ * assertion around them.
662
707
  */
663
708
  private static isLiveStep;
709
+ /** Whether a step is Piwi's own, by core's rule for a stored step. */
710
+ private static isOwnStep;
664
711
  /**
665
- * In a run that can stop (breakpoints, or a run channel to an editor or the desktop app), say of the first spec file
666
- * whose test made Playwright calls without the capture fixtures, where the stops happen, that it never stops at a
667
- * breakpoint nor at Pause, which nothing else says; the others are named in one line as the run ends
712
+ * Say of the first spec file whose test made Playwright calls without the capture fixtures what it misses in this
713
+ * run, which nothing else says: in a run that can stop (breakpoints, or a run channel to an editor or the desktop
714
+ * app, where the stops happen), its tests never stop at a breakpoint nor at Pause; in a CI run whose workers stream
715
+ * to the instance's live view, nobody can watch them. The others are named in one line as the run ends
668
716
  * (`noteOtherUncaptured`).
669
717
  */
670
718
  private noteUncaptured;
671
719
  /** The spec files past the first that ran without the capture fixtures, in one line (`noteUncaptured`). */
672
720
  private noteOtherUncaptured;
721
+ /**
722
+ * What a spec file that runs without the capture fixtures misses in this run, said of one file and of several: the
723
+ * live view only for a test with a page (`page`).
724
+ */
725
+ private uncapturedCosts;
673
726
  /** Playwright reporter hook: called when a step (including hook/fixture) begins */
674
727
  onStepBegin(test: TestCase | undefined, _result: TestResult | undefined, step: any): void;
675
728
  /** Playwright reporter hook: called when a step (including hook/fixture) ends */
@@ -678,8 +731,8 @@ declare class PiwiDashboardReporter {
678
731
  onTestEnd(test: TestCase, result: TestResult): void;
679
732
  /**
680
733
  * Add up the files a test attached, and keep its resource census; for a test
681
- * that ran without the capture fixtures, tally the browsers and contexts its
682
- * steps opened and closed.
734
+ * that ran without the capture fixtures, tally the browsers, contexts and
735
+ * pages its steps opened and closed.
683
736
  */
684
737
  private collectResources;
685
738
  /**
@@ -714,6 +767,8 @@ declare class PiwiDashboardReporter {
714
767
  onEnd(result: FullResult): Promise<{
715
768
  status?: FullResult['status'];
716
769
  } | void>;
770
+ /** Every environment snapshot of the run; none when collection is off or reading them failed. */
771
+ private readEnvironments;
717
772
  private finishRun;
718
773
  }
719
774