@piwitests/reporter 0.64.0 → 0.66.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
@@ -1,4 +1,4 @@
1
- import { FullConfig, Suite, TestCase, TestResult, FullResult } from '@playwright/test/reporter';
1
+ import { FullConfig, Suite, TestCase, TestResult, TestError, FullResult } from '@playwright/test/reporter';
2
2
  import { PlaywrightTestConfig, Locator, TestType, Page, Fixtures, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions } from '@playwright/test';
3
3
  export { PlaywrightTestConfig } from '@playwright/test';
4
4
  export { PiwiFixtures, PiwiWorkerFixtures, extendPiwiFixtures, piwiFixtures } from './internal/capture/capture-fixtures.js';
@@ -15,7 +15,10 @@ import './wire-7zsqlBoY.js';
15
15
  interface PiwiDashboardOptions {
16
16
  /** Explicitly enable or disable the reporter. Defaults to `true` when `serverUrl` is set. Set to `false` to disable even if `serverUrl` is provided. */
17
17
  enabled?: boolean;
18
- /** URL of the Piwi Dashboard server */
18
+ /**
19
+ * URL of the Piwi Dashboard server: a whole `http://` or `https://` address. Any other value leaves the reporter
20
+ * off, with a warning.
21
+ */
19
22
  serverUrl?: string;
20
23
  /**
21
24
  * When results go to the Piwi desktop app running on this machine instead.
@@ -36,15 +39,21 @@ interface PiwiDashboardOptions {
36
39
  /**
37
40
  * Time budget (ms) for the reporter's end-of-run work: delivering the last
38
41
  * live events, uploading the remaining traces and attachments, and submitting
39
- * the run. When it runs out, the reporter stops waiting for the dashboard and
40
- * saves the run's results locally; the next run for the project uploads them,
41
- * without traces or attachments. Defaults to `900000` (15 minutes). Set to `0`
42
- * for no limit. Can also be set with `PIWI_SUBMIT_TIMEOUT`.
42
+ * the run. The uploads stop a minute before it ends (a quarter of a shorter
43
+ * budget), so a streamed run is still finished. When it runs out, the
44
+ * reporter stops waiting for the dashboard and saves the run's results
45
+ * locally; the next run for the project uploads them, without traces or
46
+ * attachments. Defaults to `900000` (15 minutes). Set to `0` for no limit.
47
+ * Can also be set with `PIWI_SUBMIT_TIMEOUT`, in milliseconds too: a value
48
+ * that is not a number (`15m`) is ignored, with a warning.
43
49
  */
44
50
  submitTimeout?: number;
45
51
  /** Upload trace files to the dashboard. Defaults to `true`. */
46
52
  uploadTraces?: boolean;
47
- /** Upload the Playwright HTML report. Defaults to `true`. */
53
+ /**
54
+ * Upload the HTML report Playwright's `html` reporter writes during the run, from its `outputFolder` (or
55
+ * `PLAYWRIGHT_HTML_OUTPUT_DIR`); a report an earlier run left there is never uploaded. Defaults to `true`.
56
+ */
48
57
  uploadReport?: boolean;
49
58
  /** Upload each test's trace and attachments as soon as the test finishes (streaming mode only). Defaults to `true`. */
50
59
  liveFileUploads?: boolean;
@@ -121,11 +130,14 @@ interface PiwiDashboardOptions {
121
130
  * functions ran, from Chromium's JavaScript coverage, which is what
122
131
  * `captureCodeReach: true` records; `'functions'` adds the start and end
123
132
  * line of each function that ran, read through the dev server's modules or
124
- * the bundle's source maps; `'off'` records nothing. Paths, and line numbers
125
- * with `'functions'`, are sent, never source code or hit counts. Defaults to
126
- * `'off'`. Can also be set with `PIWI_COVERAGE_BROWSER`.
133
+ * the bundle's source maps; `'lines'` also adds the lines that ran and the
134
+ * executable lines of each file, from V8's block coverage, which slows the
135
+ * page's script down more than function coverage does; `'off'` records
136
+ * nothing. Paths, and line numbers with `'functions'` and `'lines'`, are
137
+ * sent, never source code or hit counts. Defaults to `'off'`. Can also be set
138
+ * with `PIWI_COVERAGE_BROWSER`.
127
139
  */
128
- browser?: 'off' | 'files' | 'functions';
140
+ browser?: 'off' | 'files' | 'functions' | 'lines';
129
141
  /**
130
142
  * What the server side records, from a backend built with Piwi's coverage
131
143
  * instrumentation (ASP.NET Core: `-p:PiwiCoverage=true`), which names each
@@ -299,7 +311,14 @@ interface PiwiDashboardOptions {
299
311
  * with `PIWI_PICK_LOCATOR_ON_FAIL=true`.
300
312
  */
301
313
  pickLocatorOnFailure?: boolean;
302
- /** Enable live streaming of results (falls back to batch if unsupported). Defaults to `true`. */
314
+ /**
315
+ * Enable live streaming of results (falls back to batch if unsupported). An
316
+ * interrupted stream is retried until it catches up. Live events the
317
+ * dashboard refuses, or has not taken two and a half minutes after they first
318
+ * failed, leave the live view so the later ones flow; when test results are
319
+ * among the events the dashboard never took, the run is sent again as a batch
320
+ * at its end. Defaults to `true`.
321
+ */
303
322
  streaming?: boolean;
304
323
  /**
305
324
  * Number of queued events that triggers a send during streaming: test starts
@@ -490,6 +509,8 @@ declare function wrapConfig<T extends PlaywrightTestConfig>(config: T, piwiOptio
490
509
  declare class PiwiDashboardReporter {
491
510
  private options;
492
511
  private testCases;
512
+ /** The failed and timed-out attempts collected so far: the blockers a `describe.serial` cascade links to. */
513
+ private readonly failedCases;
493
514
  private startTime;
494
515
  private playwrightVersion;
495
516
  private readonly reporterVersion;
@@ -499,6 +520,11 @@ declare class PiwiDashboardReporter {
499
520
  private skippedTests;
500
521
  private timedOutTests;
501
522
  private didNotRunTests;
523
+ /**
524
+ * Tests whose attempts read as Playwright's `unexpected` outcome (`failedEveryAttempt`), counted once their last
525
+ * attempt ended: what `maxFailures` counts.
526
+ */
527
+ private failedTestCount;
502
528
  /** Full set of tests Playwright planned to run this shard (captured in `onBegin`). */
503
529
  private plannedTests;
504
530
  /** Ids of tests that actually reported via `onTestEnd`, to find the ones that never ran. */
@@ -507,10 +533,17 @@ declare class PiwiDashboardReporter {
507
533
  private uncapturedSpecs;
508
534
  /** The live steps begun and not ended, by step, sent again when someone opens the run (`onWatched`). */
509
535
  private openSteps;
536
+ /**
537
+ * The failed attempts with retries left, by `test.id`: each is its test's last failure when no later attempt has a
538
+ * say in its outcome (`decidesOutcome`), the run stopping before the retry or the retry not running.
539
+ */
540
+ private failuresAwaitingRetry;
510
541
  /** Per-test attempt history, keyed by `test.id`; snapshotted onto every attempt's payload. */
511
542
  private attemptsByTest;
512
543
  /** The folder test files are named relative to: the Playwright config's, set in `onBegin`. */
513
544
  private testPathBase;
545
+ /** The folder the run's html reporter writes its report to, set in `onBegin`; null when the run has none. */
546
+ private htmlReport;
514
547
  /** Derived in `onBegin`, once the shard is known. */
515
548
  private instanceId;
516
549
  private shardInfo;
@@ -518,6 +551,8 @@ declare class PiwiDashboardReporter {
518
551
  /** Each planned test's external ID and the IDs two tests share, settled in `onBegin`. */
519
552
  private externalIds;
520
553
  private enabled;
554
+ /** Why the configured `serverUrl` cannot be used, which leaves the reporter off; null when it can. */
555
+ private readonly serverUrlProblem;
521
556
  /**
522
557
  * True under `playwright test --list`, where Playwright still constructs this
523
558
  * reporter and fires `onBegin`/`onEnd` but runs no tests. Registering and
@@ -530,10 +565,14 @@ declare class PiwiDashboardReporter {
530
565
  private readonly desktopReplaced;
531
566
  /** The config folder's `.env` file and the connection variables taken from it, if any. */
532
567
  private readonly viaDotEnv;
568
+ /** The `PIWI_*` variables whose values could not be read, so their options kept their defaults. */
569
+ private readonly ignoredEnv;
533
570
  private isFullRun;
534
571
  private filterDetails;
535
572
  /** Configured `maxFailures` (0 = unlimited) — disambiguates an interrupted run's unrun reason. */
536
573
  private maxFailures;
574
+ /** Each Playwright project's `dependencies`, by project name, set in `onBegin`. */
575
+ private projectDependencies;
537
576
  /** The resource censuses the capture fixtures attached, one per test attempt. */
538
577
  private resourceCensuses;
539
578
  /** Lifecycle steps of the tests that ran without the fixtures. */
@@ -560,6 +599,8 @@ declare class PiwiDashboardReporter {
560
599
  private manifests;
561
600
  /** Result events that stream once their test's server coverage is in. */
562
601
  private coverageSends;
602
+ /** The errors Playwright reported outside any test (`onError`), the first `MAX_RUN_ERRORS` of them. */
603
+ private readonly runErrors;
563
604
  private httpClient;
564
605
  private uploader;
565
606
  private fileHandler;
@@ -598,7 +639,18 @@ declare class PiwiDashboardReporter {
598
639
  private externalIdFields;
599
640
  /** Playwright reporter hook: called when an individual test begins */
600
641
  onTestBegin(test: TestCase, result: TestResult): void;
601
- /** Track suite-level setup steps (beforeAll/afterAll) not tied to any test */
642
+ /**
643
+ * Playwright reporter hook: an error outside any test, such as a global setup that threw, a spec file that did not
644
+ * load (`No tests found` and a web server that did not start come the same way, before any test), or a worker
645
+ * fixture whose teardown threw. The run keeps the first `MAX_RUN_ERRORS`, with what may be a secret hidden, and sends
646
+ * them with its end.
647
+ */
648
+ onError(error: TestError): void;
649
+ /**
650
+ * The steps outside any test, for the run's timeline. Playwright 1.59 and later, the oldest the reporter supports,
651
+ * give every hook step to a test, `beforeAll` and `afterAll` hooks and worker fixture setup included, so it stays
652
+ * empty.
653
+ */
602
654
  private setupSteps;
603
655
  /** Step categories streamed live while the run executes. */
604
656
  private static readonly LIVE_STEP_CATEGORIES;
@@ -641,9 +693,20 @@ declare class PiwiDashboardReporter {
641
693
  * carry no result, so they're emitted with zero duration and no error. In
642
694
  * streaming mode they're queued as complete events so the pre-finish drain
643
695
  * sends them alongside the rest. The `reason` (global timeout / max failures /
644
- * interrupted) is resolved once from the overall run status by the caller.
696
+ * interrupted) is resolved once from the overall run status by the caller. A
697
+ * test declared skipped (`test.skip()`, `test.fixme()`, a skipped describe)
698
+ * is sent as `skipped`: it is a skip whether the run reached it or not. A test
699
+ * of a project whose dependency failed is a `dependency-failure`, blocked by
700
+ * that failure (`dependencyBlocker`).
645
701
  */
646
702
  private materializeUnrunTests;
703
+ /**
704
+ * The failure that kept a test from running when a project its project depends on failed: the first test that failed
705
+ * every attempt with a say in its outcome (`failedEveryAttempt`) in a project of its project's `dependencies`,
706
+ * directly or through another project. Playwright runs no test of a project one of whose dependencies failed. Null
707
+ * for a test whose dependencies had no such failure.
708
+ */
709
+ private dependencyBlocker;
647
710
  /**
648
711
  * Playwright reporter hook: called when the full test run finishes. Fails the run when two tests share an external
649
712
  * ID and `externalId.onDuplicate` is `'fail'`.