@alwaysmeticulous/sdk-bundles-api 2.290.2 → 2.292.0

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { InProgressTestRun } from "./replay-orchestrator/bundle-to-sdk/execute-s
 export { InProgressTestRunChunk, ExecuteTestRunChunkResult, TestRunChunkExecution, } from "./replay-orchestrator/bundle-to-sdk/execute-scheduled-test-run-chunk";
 export { ReplayAndStoreResultsResult, ReplayExecution, BeforeUserEventResult, IndexedReplayableEvent, } from "./replay-orchestrator/bundle-to-sdk/execute-replay";
 export { ScreenshotDiffData } from "./replay-orchestrator/bundle-to-sdk/execute-replay";
-export { MeticulousPublicApi, MeticulousPressureObserver, MeticulousPressureObserverConstructor, MeticulousPressureRecord, MeticulousPressureSource, MeticulousPressureState, } from "./window-api/public-window-api";
+export { MeticulousPublicApi, MeticulousPressureObserver, MeticulousPressureObserverConstructor, MeticulousPressureRecord, MeticulousPressureSource, MeticulousPressureState, RecordCustomSnapshotOptions, OnBeforeScreenshotListener, OnBeforeScreenshotListenerOptions, OnReplayCompletionListener, OnReplayCompletionListenerOptions, } from "./window-api/public-window-api";
 export { MeticulousPrivateApi } from "./window-api/private-window-api";
 export { BackendRecorderConfig } from "./backend-recorder/sdk-to-bundle/init-backend-recorder";
 export { BackendRecorderHandle } from "./backend-recorder/bundle-to-sdk/init-backend-recorder";

package/dist/replay-orchestrator/sdk-to-bundle/execute-replay.d.ts

@@ -297,6 +297,9 @@ export interface GeneratedByTestRun {
 export interface GeneratedByReplayCommand {
     type: "replayCommand";
 }
+export type SessionStartUrlTransform = {
+    type: "extract-hash-route";
+};
 export interface AppUrlConfig {
     /**
      * If set, we will ensure that the appUrl pathname is prefixed with this value for the initial navigation.
@@ -325,6 +328,15 @@ export interface AppUrlConfig {
      * List of query parameters to set to `""` from the app URL before the initial navigation.
      */
     queryParamsToEmpty?: string[];
+    /**
+     * If set, transforms the session start URL before computing the initial navigation URL.
+     *
+     * `extract-hash-route`: when the session URL has a hash that begins with `#/` (SPA hash routing),
+     * promotes the hash content to the real pathname and discards the original pathname.
+     * Example: `https://preview.example.com/pr-123/#/dashboard/settings` → pathname `/dashboard/settings`, no hash.
+     * Sessions without a `#/` hash are returned unchanged.
+     */
+    sessionStartUrlTransform?: SessionStartUrlTransform;
 }
 export interface NetworkDebuggingOptions {
     requestRegexes: string[];

package/dist/window-api/public-window-api.d.ts

@@ -13,6 +13,43 @@ export interface MeticulousPublicApiCommon {
     isRunningAsTest?: boolean;
     context: MeticulousPublicContextApi;
 }
+/**
+ * Options for {@link MeticulousPublicReplayApi.recordCustomSnapshot}.
+ */
+export interface RecordCustomSnapshotOptions<T = unknown> {
+    /**
+     * The kind of snapshot. Used to group snapshots so a custom check can fetch
+     * every snapshot of a given type across the test run. Must match
+     * `^[a-z0-9-]{1,64}$` and must not collide with a built-in snapshot type
+     * (e.g. "network-requests").
+     */
+    snapshotType: string;
+    /** The data to snapshot. Must be JSON-serializable. */
+    data: T;
+    /**
+     * Optional version number for the snapshot's shape/semantics. If the version
+     * differs between the base and head replays, a failing custom check can be
+     * caveated in the UI (the difference may be due to the snapshot format
+     * changing rather than a real regression). Defaults to 0 when omitted.
+     */
+    versionNumber?: number;
+}
+/** Details passed to an {@link OnBeforeScreenshotListener}. */
+export interface OnBeforeScreenshotListenerOptions {
+    /**
+     * The stage the upcoming screenshot will be tagged with (e.g.
+     * "screenshot-after-event-12"). Snapshots recorded during this listener are
+     * tagged with the same stage.
+     */
+    stageDuringSession: string;
+}
+export type OnBeforeScreenshotListener = (options: OnBeforeScreenshotListenerOptions) => void | Promise<void>;
+/** Details passed to an {@link OnReplayCompletionListener}. */
+export interface OnReplayCompletionListenerOptions {
+    /** The id of the session being replayed. */
+    sessionId: string;
+}
+export type OnReplayCompletionListener = (options: OnReplayCompletionListenerOptions) => void | Promise<void>;
 export interface MeticulousPublicReplayApi {
     /**
      * Call this method to pause the Meticulous replay while your code performs an asynchronous operation
@@ -48,6 +85,63 @@ export interface MeticulousPublicReplayApi {
     recordCustomEvent(type: string, serializedData: string): {
         success: boolean;
     };
+    /**
+     * Record a snapshot of custom data at the current point in the replay, for use
+     * by a custom check. The snapshot is persisted alongside the replay and
+     * auto-tagged with the stage during the session at which it was taken
+     * (identified by the next screenshot, e.g. "screenshot-after-event-12" or
+     * "final-state"), so a custom check can later align and compare the base and
+     * head snapshots of the same {@link RecordCustomSnapshotOptions.snapshotType}
+     * across a test run.
+     *
+     * Use this to capture custom data that Meticulous does not snapshot natively,
+     * for use by a custom check.
+     *
+     * Snapshots are only collected when custom snapshotting is enabled for the
+     * project; otherwise this is a no-op (the data is still validated).
+     *
+     * @throws if `data` is not JSON-serializable, or if `snapshotType` is invalid
+     * (it must match `^[a-z0-9-]{1,64}$` and must not collide with a built-in
+     * snapshot type such as "network-requests").
+     */
+    recordCustomSnapshot<T = unknown>(options: RecordCustomSnapshotOptions<T>): {
+        success: boolean;
+    };
+    /**
+     * Register a listener invoked immediately before each screenshot is taken,
+     * once the page has settled. Use it to inspect the state of the page and
+     * {@link recordCustomSnapshot | record a snapshot} of it at each screenshot
+     * point. Any snapshots recorded synchronously (or awaited) within the listener
+     * are tagged with the screenshot about to be taken.
+     *
+     * The listener must be **read-only**: it runs after the page has settled but
+     * before the screenshot is captured, so mutating the DOM (or triggering a
+     * re-render) would change the captured screenshot.
+     *
+     * Prefer **synchronous** work. The listener is awaited on the screenshot
+     * critical path and bounded by an internal timeout, and during replay the
+     * page's timers run on (frozen) virtual time — so async work that relies on
+     * real timers (e.g. `setTimeout`) to make progress will not complete and will
+     * be skipped.
+     *
+     * Listeners are only invoked when custom snapshotting is enabled for the
+     * project.
+     */
+    addOnBeforeScreenshotListener(listener: OnBeforeScreenshotListener): void;
+    /**
+     * Register a listener invoked once when the replay completes. Use it to
+     * capture end-of-replay information — for example final performance metrics —
+     * via {@link recordCustomSnapshot}. Snapshots recorded within the listener are
+     * tagged with the "final-state" stage.
+     *
+     * As with {@link addOnBeforeScreenshotListener}, the listener is bounded by an
+     * internal timeout and timer-based async work may not complete under virtual
+     * time, so prefer synchronous capture.
+     *
+     * Listeners are only invoked when custom snapshotting is enabled for the
+     * project.
+     */
+    addOnReplayCompletionListener(listener: OnReplayCompletionListener): void;
     /**
      * True only in case the performance data associated with this replay is
      * significant to benchmark the performance of the application.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwaysmeticulous/sdk-bundles-api",
-  "version": "2.290.2",
+  "version": "2.292.0",
   "description": "Meticulous common types",
   "license": "ISC",
   "main": "dist/index.js",
@@ -9,7 +9,7 @@
     "dist"
   ],
   "dependencies": {
-    "@alwaysmeticulous/api": "2.290.2"
+    "@alwaysmeticulous/api": "2.292.0"
   },
   "author": {
     "name": "The Meticulous Team",