@empiricalrun/playwright-utils 0.58.5 → 0.59.0

package/dist/generated/api-worker-openapi.d.ts

@@ -255,6 +255,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/test-runs/{id}/shard-plan": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * ⚙️ 🧪 Store a test run's shard plan
+         * @description Stores the partition of a run's test selection across its run_test shards, keyed by the external run_id. Each shard reads its own slice back from `/{id}/shards/{shard_index}/assigned-tests` to build a `--test-list`. Idempotent: the first plan for a run wins.
+         */
+        post: operations["createTestRunShardPlan"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/test-runs/{id}/shards": {
         parameters: {
             query?: never;
@@ -275,6 +295,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/test-runs/{id}/shards/{shard_index}/assigned-tests": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * ⚙️ 🧪 Get test run shard assigned tests
+         * @description Returns the duration-based shard plan's test-case ids for one shard, addressed by the run's external run_id. Used by the test-run-worker to build its `--test-list`. Returns 417 when the run has no plan, so the worker falls back to Playwright's `--shard=i/N` split.
+         */
+        get: operations["getTestRunShardAssignedTests"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/test-runs/{id}/shards/{shard_index}/resume": {
         parameters: {
             query?: never;
@@ -355,6 +395,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/test-runs/{id}/test-case-durations": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * ⚙️ 🧪 Get test case durations for shard planning
+         * @description Returns the run's project's 7-day average duration per test case, keyed by the normalized 41-char Playwright test id, addressed by the run's external run_id. Used by the `run_setup` container to pack a shard plan: the analytics token is account-scoped and cannot be handed to a sandbox running customer test code, so the api-worker holds it and serves the numbers. Project-wide rather than per-run — the container filters to the tests it listed. A project with no history returns an empty object; a broken analytics query returns 503, so the container can tell the two apart and fall back rather than plan off nothing.
+         */
+        get: operations["getTestRunTestCaseDurations"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/test-runs/{id}/triage-session": {
         parameters: {
             query?: never;
@@ -2433,26 +2493,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/chat-sessions/{id}/sandbox/terminal-session": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * ⚙️ Create a sandbox terminal session
-         * @description Creates a PTY session on the sandbox and returns the WebSocket URL and token to connect to it. Super-admin only.
-         */
-        post: operations["createChatSessionSandboxTerminalSession"];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/api/chat-sessions/{id}/session-state": {
         parameters: {
             query?: never;
@@ -2593,6 +2633,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/chat-sessions/sandbox/protected-branches": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * ⚙️ List branches the sandbox may not push to
+         * @description Returns the project's default branch and the chat session's base branch. The sandbox git proxy blocks pushes to these. The session is derived from the sandbox-delegation principal.
+         */
+        get: operations["getChatSessionSandboxProtectedBranches"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/chat-sessions/users": {
         parameters: {
             query?: never;
@@ -8920,6 +8980,10 @@ export interface components {
             /** @description Human-readable error message. */
             error: string;
         };
+        SandboxProtectedBranches: {
+            /** @description Branch names the sandbox must not push to. */
+            branches: string[];
+        };
         SandboxActionSuccess: {
             /** @description Always true when the action succeeded. */
             success: boolean;
@@ -8986,14 +9050,6 @@ export interface components {
             /** @description Human-readable error message. */
             error: string;
         };
-        SandboxTerminalSession: {
-            /** @description WebSocket URL for the PTY session. */
-            ws_url: string;
-            /** @description Auth token for the terminal WebSocket. */
-            token: string;
-            /** @description Error message, or null on success. */
-            error: string | null;
-        };
         SubscribeChatSessionResponse: {
             data: {
                 already_waiting: boolean;
@@ -10143,8 +10199,6 @@ export interface components {
             id: number;
             /** @description ISO 8601 creation timestamp. */
             created_at: string;
-            /** @description Test case slug. */
-            slug: string | null;
             /** @description Playwright test ID. */
             pw_test_id: string | null;
             /** @description Test run ID. */
@@ -10367,7 +10421,6 @@ export interface components {
                     /** @enum {string} */
                     job_type: "merge_reports";
                     storage_bucket?: string;
-                    assigned_shard_manifest_formula?: string;
                     resume_run_from_shard?: number;
                 } | null;
             };
@@ -10555,6 +10608,29 @@ export interface components {
                 resume_from: number | null;
             };
         };
+        TestRunTestCaseDurationsResponse: {
+            data: {
+                /** @description Length of the analytics window the averages cover. */
+                days: number;
+                /** @description Per-test-case history, keyed by the normalized 41-char Playwright test id. */
+                durations: {
+                    [key: string]: {
+                        /** @description Mean total duration over the window, in ms. */
+                        avg_duration_total: number;
+                        /** @description Results the average was taken over. */
+                        total_runs: number;
+                    };
+                };
+            };
+        };
+        TestRunShardAssignedTestsResponse: {
+            data: {
+                /** @description Playwright test-case ids this shard is assigned to execute. */
+                test_case_ids: string[];
+                /** @description Shard count the plan was built for. */
+                total_shards: number;
+            };
+        };
         TestRunLogsResponse: {
             /** @description Response payload. */
             data: {
@@ -10607,7 +10683,7 @@ export interface components {
             /** @description Zero-based shard index, when stopping a sharded run. */
             shard_index?: number;
             /**
-             * @description Job type of the shard to stop. merge_reports and run_setup share shard_index 0. Defaults to merge_reports for index 0 (legacy callers), run_test otherwise.
+             * @description Job type of the shard to stop. merge_reports and run_setup share shard_index 0. When omitted, the job is resolved from the run's shard rows; an index that carries more than one stoppable job is a 400. `run_setup` is never stoppable and is always rejected.
              * @enum {string}
              */
             job_type?: "run_test" | "merge_reports" | "run_setup";
@@ -10655,20 +10731,70 @@ export interface components {
             };
         };
         PutRunManifestRequest: {
-            /** @description Structured scheduled tests (preferred). */
-            tests?: {
+            /** @description Structured scheduled tests. */
+            tests: {
                 /** @description Full test title. */
                 name: string;
                 /** @description Playwright test id, if known. */
                 pw_test_id?: string | null;
             }[];
-            /** @description Legacy base64-gzip manifest blob. Ignored when `tests` is present. */
-            run_manifest?: string;
+            /** @description Scheduled dependency groups (serial blocks). */
+            dependency_groups?: {
+                /** @description Stable group id. */
+                id: string;
+                /**
+                 * @description Only Playwright serial groups today.
+                 * @enum {string}
+                 */
+                kind: "playwright_serial";
+                /** @description Members in execution order. */
+                members: {
+                    /** @description Playwright test id of the member. */
+                    test_case_id: string;
+                    /** @description 0-based execution order within the group. */
+                    dependency_order: number;
+                }[];
+            }[];
             /** @description Zero-based shard index, when the run is sharded. */
             shard_index?: number;
             /** @description Total number of shards, when the run is sharded. */
             total_shards?: number;
         };
+        ShardPlanResponse: {
+            /** @description Response payload. */
+            data: {
+                /** @description Rows inserted. Zero when the run was already planned — the first plan wins and a retried POST is a no-op. */
+                shards_written: number;
+                /** @description Tests across the posted partition. */
+                total_tests: number;
+            };
+        };
+        PostShardPlanRequest: {
+            /** @description Shard count this partition was built for. Stored on every row and checked against the shard's own total_shards when the plan is read. */
+            total_shards: number;
+            /** @description One entry per run_test shard. */
+            shards: {
+                /** @description 1-based index of the run_test shard. Index 0 is the run_setup job and never carries an assignment. */
+                shard_index: number;
+                /** @description Tests assigned to this shard. */
+                tests: {
+                    /** @description Playwright test id (`pw_test_id`) assigned to this shard. */
+                    id: string;
+                    /** @description Scheduled test line (`[project] › file › suite › title`). Not stored yet; the server-written run manifest is its consumer. */
+                    name: string;
+                }[];
+            }[];
+            /** @description How the partition was chosen, stored verbatim for provenance (e.g. `equal split over the canonical listing`). */
+            reason?: string;
+            /** @description Modelled wall-clock of the slowest shard, in ms. */
+            predicted_makespan_ms?: number;
+            /** @description Modelled wall-clock at the ceiling — what the run would have done without the reduction, in ms. */
+            baseline_makespan_ms?: number;
+            /** @description Heaviest single schedulable unit, in ms. The floor no shard count can beat. */
+            longest_unit_ms?: number;
+            /** @description Fraction of planned tests that had a real historical duration. */
+            coverage?: number;
+        };
         SkipTestRunResponse: {
             data: {
                 /** @description ID of the GitHub check run created as skipped, or null if no GitHub reporter app is installed for the repo. */
@@ -10731,6 +10857,8 @@ export interface components {
             last_commit_before_run_started_at: string | null;
             /** @description Snoozes matching this case at read time. */
             snooze_info: components["schemas"]["TestRunCaseSnoozeInfo"][];
+            /** @description Attempts that never ran because an earlier member of this case's Playwright serial group failed on the same attempt. Null when the case is not in a snapshotted group or when nothing was blocked. */
+            skipped_attempts: components["schemas"]["TestRunCaseSkippedAttempt"][] | null;
         };
         TestRunCaseRetryDetail: {
             /** @description Zero-based retry attempt index. */
@@ -10804,6 +10932,19 @@ export interface components {
             /** @description Environment the snooze is scoped to, if any. */
             scoped_to_environment_id: number | null;
         };
+        TestRunCaseSkippedAttempt: {
+            /** @description Attempt index this explains. */
+            retry_index: number;
+            /** @description The serial-group member that blocked this attempt. */
+            blocked_by: {
+                /** @description Playwright test id of the blocking test. */
+                pw_test_id: string | null;
+                /** @description Title of the blocking test. */
+                name: string;
+                /** @description The blocking test's outcome on this attempt. */
+                status: string;
+            };
+        };
         GetTestRunCaseResponse: {
             /** @description Response payload. */
             data: {
@@ -10845,6 +10986,8 @@ export interface components {
                 last_commit_before_run_started_at: string | null;
                 /** @description Snoozes matching this case at read time. */
                 snooze_info: components["schemas"]["TestRunCaseSnoozeInfo"][];
+                /** @description Attempts that never ran because an earlier member of this case's Playwright serial group failed on the same attempt. Null when the case is not in a snapshotted group or when nothing was blocked. */
+                skipped_attempts: components["schemas"]["TestRunCaseSkippedAttempt"][] | null;
             };
         };
         UiGetTestRunResponse: {
@@ -13007,6 +13150,51 @@ export interface operations {
             };
         };
     };
+    createTestRunShardPlan: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description External run_id of the test run. */
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["PostShardPlanRequest"];
+            };
+        };
+        responses: {
+            /** @description The shard plan was stored. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ShardPlanResponse"];
+                };
+            };
+            /** @description The posted plan is not a valid partition. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Test run not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     listTestRunShards: {
         parameters: {
             query?: never;
@@ -13039,6 +13227,49 @@ export interface operations {
             };
         };
     };
+    getTestRunShardAssignedTests: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description External run_id of the test run. */
+                id: number;
+                /** @description Zero-based shard index within the run. */
+                shard_index: number | null;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The shard's assigned test-case ids. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TestRunShardAssignedTestsResponse"];
+                };
+            };
+            /** @description Test run not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description No shard plan for this run or shard. */
+            417: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     getTestRunShardResume: {
         parameters: {
             query?: never;
@@ -13202,6 +13433,47 @@ export interface operations {
             };
         };
     };
+    getTestRunTestCaseDurations: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Test run identifier (database id or external run_id). */
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The project's test-case duration history. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TestRunTestCaseDurationsResponse"];
+                };
+            };
+            /** @description Test run not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Analytics is unavailable. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     createTestRunTriageSession: {
         parameters: {
             query?: never;
@@ -18748,8 +19020,8 @@ export interface operations {
             content: {
                 "application/json": {
                     message: string;
-                    /** @enum {string|null} */
-                    send_action?: "queue" | "stop" | "follow_up" | null;
+                    /** @enum {string} */
+                    send_action: "steer" | "follow_up" | "stop";
                     created_by?: string | null;
                 };
             };
@@ -19212,65 +19484,6 @@ export interface operations {
             };
         };
     };
-    createChatSessionSandboxTerminalSession: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path: {
-                /** @description Chat session ID. */
-                id: number;
-            };
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            /** @description Terminal session connection details. */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["SandboxTerminalSession"];
-                };
-            };
-            /** @description Invalid request. */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Forbidden. */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["SandboxTerminalSession"];
-                };
-            };
-            /** @description Sandbox not found. */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["SandboxTerminalSession"];
-                };
-            };
-            /** @description Failed to create terminal session. */
-            500: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["SandboxTerminalSession"];
-                };
-            };
-        };
-    };
     getChatSessionState: {
         parameters: {
             query?: {
@@ -19576,6 +19789,44 @@ export interface operations {
             };
         };
     };
+    getChatSessionSandboxProtectedBranches: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Protected branches. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SandboxProtectedBranches"];
+                };
+            };
+            /** @description The caller is not a sandbox principal. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SandboxErrorMessage"];
+                };
+            };
+            /** @description Chat session not found. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SandboxErrorMessage"];
+                };
+            };
+        };
+    };
     listChatSessionUsers: {
         parameters: {
             query?: {