@testrelic/playwright-analytics 2.13.1 → 2.14.0-next.114

package/dist/index.d.cts

@@ -5,6 +5,58 @@ export { testRelicFixture } from './fixture.cjs';
 export { testRelicApiFixture } from './api-fixture.cjs';
 import { PlaywrightTestConfig, defineConfig as defineConfig$1 } from '@playwright/test';
 
+/**
+ * Cloud upload receipt — the honest record of whether a run reached the platform.
+ *
+ * `summary.json` has always carried `testRunId`, and consumers (TestRelic Studio
+ * among them) read its presence as proof the run was uploaded. It is not proof:
+ * `testRunId` is `config.testRunId ?? randomUUID()`, generated locally in `onBegin`
+ * and written on every run — including a fully offline one, which then renders as
+ * "Uploaded" behind a dashboard link that 404s.
+ *
+ * The platform does not mint run ids either — `POST /runs/init` and `POST /runs`
+ * both file the run under the id the SDK sent — so there is no server-side id to
+ * record instead. What the SDK *does* know, and never wrote down, is whether the
+ * platform acknowledged the run. That is what `cloudUpload` carries.
+ *
+ * The block is written on EVERY run, so a consumer can distinguish three states:
+ *   - block absent        → an SDK too old to report a verdict; treat as unknown
+ *   - `acknowledged:false` → the run did not reach the platform, and `detail` says why
+ *   - `acknowledged:true`  → the platform accepted the run under `runId`
+ *
+ * It is written twice per run, both times atomically (tmp + rename): once with the
+ * pre-upload state, and again once the upload settles. A process killed between the
+ * two leaves the earlier, more conservative verdict on disk — this block under-claims
+ * when it is wrong, never over-claims.
+ */
+
+/**
+ * Whether the platform acknowledged this run, and what it did with it.
+ * Written to `summary.json` as `cloudUpload` on every run.
+ */
+interface CloudUploadReceipt {
+    /** Cloud mode was on and a strategy the reporter acts on was selected. */
+    readonly attempted: boolean;
+    /** The platform accepted the run — realtime `/runs/init`, or the batch `POST /runs`. */
+    readonly acknowledged: boolean;
+    /** The id the run was filed under on the platform, or null when never acknowledged. */
+    readonly runId: string | null;
+    /** The ingest endpoint the run was sent to, or null when nothing was sent. */
+    readonly endpoint: string | null;
+    /** The run was closed out — realtime finalize returned ok, or the batch upload landed. */
+    readonly finalized: boolean;
+    /** Artifacts the platform confirmed it stored. */
+    readonly artifactsUploaded: number;
+    /** Artifacts offered for upload. */
+    readonly artifactsTotal: number;
+    /** Short plain reason when the run was not acknowledged. Null once it was. */
+    readonly detail: string | null;
+}
+/** A streaming summary carrying the upload receipt. */
+type WithCloudUpload<T> = T & {
+    readonly cloudUpload: CloudUploadReceipt;
+};
+
 /**
  * JSON schema version for the analytics timeline output.
  */
@@ -59,4 +111,4 @@ declare function recordNavigation(testInfo: {
     }>;
 } | null | undefined, url: string, navigationType?: NavigationType): void;
 
-export { SCHEMA_VERSION, defineConfig, recordNavigation };
+export { type CloudUploadReceipt, SCHEMA_VERSION, type WithCloudUpload, defineConfig, recordNavigation };

package/dist/index.d.ts

@@ -5,6 +5,58 @@ export { testRelicFixture } from './fixture.js';
 export { testRelicApiFixture } from './api-fixture.js';
 import { PlaywrightTestConfig, defineConfig as defineConfig$1 } from '@playwright/test';
 
+/**
+ * Cloud upload receipt — the honest record of whether a run reached the platform.
+ *
+ * `summary.json` has always carried `testRunId`, and consumers (TestRelic Studio
+ * among them) read its presence as proof the run was uploaded. It is not proof:
+ * `testRunId` is `config.testRunId ?? randomUUID()`, generated locally in `onBegin`
+ * and written on every run — including a fully offline one, which then renders as
+ * "Uploaded" behind a dashboard link that 404s.
+ *
+ * The platform does not mint run ids either — `POST /runs/init` and `POST /runs`
+ * both file the run under the id the SDK sent — so there is no server-side id to
+ * record instead. What the SDK *does* know, and never wrote down, is whether the
+ * platform acknowledged the run. That is what `cloudUpload` carries.
+ *
+ * The block is written on EVERY run, so a consumer can distinguish three states:
+ *   - block absent        → an SDK too old to report a verdict; treat as unknown
+ *   - `acknowledged:false` → the run did not reach the platform, and `detail` says why
+ *   - `acknowledged:true`  → the platform accepted the run under `runId`
+ *
+ * It is written twice per run, both times atomically (tmp + rename): once with the
+ * pre-upload state, and again once the upload settles. A process killed between the
+ * two leaves the earlier, more conservative verdict on disk — this block under-claims
+ * when it is wrong, never over-claims.
+ */
+
+/**
+ * Whether the platform acknowledged this run, and what it did with it.
+ * Written to `summary.json` as `cloudUpload` on every run.
+ */
+interface CloudUploadReceipt {
+    /** Cloud mode was on and a strategy the reporter acts on was selected. */
+    readonly attempted: boolean;
+    /** The platform accepted the run — realtime `/runs/init`, or the batch `POST /runs`. */
+    readonly acknowledged: boolean;
+    /** The id the run was filed under on the platform, or null when never acknowledged. */
+    readonly runId: string | null;
+    /** The ingest endpoint the run was sent to, or null when nothing was sent. */
+    readonly endpoint: string | null;
+    /** The run was closed out — realtime finalize returned ok, or the batch upload landed. */
+    readonly finalized: boolean;
+    /** Artifacts the platform confirmed it stored. */
+    readonly artifactsUploaded: number;
+    /** Artifacts offered for upload. */
+    readonly artifactsTotal: number;
+    /** Short plain reason when the run was not acknowledged. Null once it was. */
+    readonly detail: string | null;
+}
+/** A streaming summary carrying the upload receipt. */
+type WithCloudUpload<T> = T & {
+    readonly cloudUpload: CloudUploadReceipt;
+};
+
 /**
  * JSON schema version for the analytics timeline output.
  */
@@ -59,4 +111,4 @@ declare function recordNavigation(testInfo: {
     }>;
 } | null | undefined, url: string, navigationType?: NavigationType): void;
 
-export { SCHEMA_VERSION, defineConfig, recordNavigation };
+export { type CloudUploadReceipt, SCHEMA_VERSION, type WithCloudUpload, defineConfig, recordNavigation };