doc-detective-common 4.23.0 → 4.24.0

package/dist/types/generated/step_v3.d.ts

@@ -5,7 +5,7 @@
 /**
  * A step in a test.
  */
-export type Step = (Common & CheckLink) | (Common1 & Click) | (Common2 & Find) | (Common3 & GoTo) | (Common4 & HttpRequest) | (Common5 & RunShell) | (Common6 & RunCode) | (Common7 & RunBrowserScript) | (Common8 & Type) | (Common9 & Screenshot) | (Common10 & SaveCookie) | (Common11 & Record) | (Common12 & StopRecord) | (Common13 & CloseSurface) | (Common14 & StartSurface) | (Common15 & LoadVariables) | (Common16 & DragAndDrop) | (Common17 & LoadCookie) | (Common18 & Wait);
+export type Step = (Common & CheckLink) | (Common1 & Click) | (Common2 & Find) | (Common3 & GoTo) | (Common4 & HttpRequest) | (Common5 & RunShell) | (Common6 & RunCode) | (Common7 & RunBrowserScript) | (Common8 & Type) | (Common9 & Screenshot) | (Common10 & SaveCookie) | (Common11 & Record) | (Common12 & StopRecord) | (Common13 & CloseSurface) | (Common14 & StartSurface) | (Common15 & LoadVariables) | (Common16 & DragAndDrop) | (Common17 & LoadCookie) | (Common18 & Swipe) | (Common19 & Wait);
 /**
  * A condition expression, or an array of expressions combined with logical AND.
  */
@@ -1218,6 +1218,130 @@ export type Routing74 = {
 export type Routing75 = {
     [k: string]: unknown;
 };
+/**
+ * Swipe (or scroll) a surface in a direction or between two points. The direction is the virtual finger's motion: swiping up moves content up, revealing content further down the page. Works on app and browser surfaces.
+ */
+export type Swipe1 = SwipeSimple | SwipeDirectional | SwipePointToPoint;
+/**
+ * Direction the virtual finger moves. `up` reveals content below; `left` reveals content to the right (for example, the next carousel card).
+ */
+export type SwipeSimple = "up" | "down" | "left" | "right";
+/**
+ * Direction the virtual finger moves. `up` reveals content below; `left` reveals content to the right (for example, the next carousel card).
+ */
+export type SwipeSimple1 = "up" | "down" | "left" | "right";
+/**
+ * Browser engine keyword. Targets that browser. Steps that can only ever act on a browser (not a background process) restrict the bare-string form to this enum, so a process name here is rejected at validation time instead of failing at runtime.
+ */
+export type SurfaceByBrowserEngine5 = "chrome" | "firefox" | "safari" | "webkit" | "edge";
+/**
+ * Which window to act on. Omit to use the active window.
+ */
+export type WindowTabSelector16 = ByIndex20 | ByName20 | ByCriteria20;
+/**
+ * Index in creation order. Negative counts from the end; `-1` is the newest.
+ */
+export type ByIndex20 = number;
+/**
+ * Name assigned when the window/tab was opened (goTo `newTab`/`newWindow`). The integer branch is listed first because Ajv validates with coerceTypes — string-first would coerce integer indexes into name strings.
+ */
+export type ByName20 = string;
+/**
+ * Which tab to act on. Omit to use the active tab. Without `window`, the selector searches every tab in creation order — including tabs the page opened itself.
+ */
+export type WindowTabSelector17 = ByIndex21 | ByName21 | ByCriteria21;
+/**
+ * Index in creation order. Negative counts from the end; `-1` is the newest.
+ */
+export type ByIndex21 = number;
+/**
+ * Name assigned when the window/tab was opened (goTo `newTab`/`newWindow`). The integer branch is listed first because Ajv validates with coerceTypes — string-first would coerce integer indexes into name strings.
+ */
+export type ByName21 = string;
+/**
+ * Which app window to act on. Omit to use the active window. Apps have windows, no tabs.
+ */
+export type AppWindowSelector4 = ByIndex22 | ByName22 | ByCriteria22;
+/**
+ * Index in creation order. Negative counts from the end; `-1` is the newest (e.g. a dialog the app just opened).
+ */
+export type ByIndex22 = number;
+/**
+ * Assigned window name. The integer branch is listed first because Ajv validates with coerceTypes — string-first would coerce integer indexes into name strings.
+ */
+export type ByName22 = string;
+/**
+ * Browser engine keyword. Targets that browser. Steps that can only ever act on a browser (not a background process) restrict the bare-string form to this enum, so a process name here is rejected at validation time instead of failing at runtime.
+ */
+export type SurfaceByBrowserEngine6 = "chrome" | "firefox" | "safari" | "webkit" | "edge";
+/**
+ * Which window to act on. Omit to use the active window.
+ */
+export type WindowTabSelector18 = ByIndex23 | ByName23 | ByCriteria23;
+/**
+ * Index in creation order. Negative counts from the end; `-1` is the newest.
+ */
+export type ByIndex23 = number;
+/**
+ * Name assigned when the window/tab was opened (goTo `newTab`/`newWindow`). The integer branch is listed first because Ajv validates with coerceTypes — string-first would coerce integer indexes into name strings.
+ */
+export type ByName23 = string;
+/**
+ * Which tab to act on. Omit to use the active tab. Without `window`, the selector searches every tab in creation order — including tabs the page opened itself.
+ */
+export type WindowTabSelector19 = ByIndex24 | ByName24 | ByCriteria24;
+/**
+ * Index in creation order. Negative counts from the end; `-1` is the newest.
+ */
+export type ByIndex24 = number;
+/**
+ * Name assigned when the window/tab was opened (goTo `newTab`/`newWindow`). The integer branch is listed first because Ajv validates with coerceTypes — string-first would coerce integer indexes into name strings.
+ */
+export type ByName24 = string;
+/**
+ * Which app window to act on. Omit to use the active window. Apps have windows, no tabs.
+ */
+export type AppWindowSelector5 = ByIndex25 | ByName25 | ByCriteria25;
+/**
+ * Index in creation order. Negative counts from the end; `-1` is the newest (e.g. a dialog the app just opened).
+ */
+export type ByIndex25 = number;
+/**
+ * Assigned window name. The integer branch is listed first because Ajv validates with coerceTypes — string-first would coerce integer indexes into name strings.
+ */
+export type ByName25 = string;
+/**
+ * A condition expression, or an array of expressions combined with logical AND.
+ */
+export type Condition38 = string | [string, ...string[]];
+/**
+ * A condition expression, or an array of expressions combined with logical AND.
+ */
+export type Condition39 = string | [string, ...string[]];
+/**
+ * A single dynamic-routing entry: an optional condition (`if`) plus exactly one routing action. Attached to a step or test handler (`onPass`, `onFail`, `onWarning`, `onSkip`). For step-level handlers, `continue`, `stop`, `retry`, and `goToStep` are evaluated at runtime; `goToTest` is validated but not yet executed (deferred at step scope). For test-level handlers, `continue`, `stop`, and `goToTest` are evaluated at runtime (test scope; `goToTest` jumps to a test within the spec), while `retry` and `goToStep` are not applicable at test scope.
+ */
+export type Routing76 = {
+    [k: string]: unknown;
+};
+/**
+ * A single dynamic-routing entry: an optional condition (`if`) plus exactly one routing action. Attached to a step or test handler (`onPass`, `onFail`, `onWarning`, `onSkip`). For step-level handlers, `continue`, `stop`, `retry`, and `goToStep` are evaluated at runtime; `goToTest` is validated but not yet executed (deferred at step scope). For test-level handlers, `continue`, `stop`, and `goToTest` are evaluated at runtime (test scope; `goToTest` jumps to a test within the spec), while `retry` and `goToStep` are not applicable at test scope.
+ */
+export type Routing77 = {
+    [k: string]: unknown;
+};
+/**
+ * A single dynamic-routing entry: an optional condition (`if`) plus exactly one routing action. Attached to a step or test handler (`onPass`, `onFail`, `onWarning`, `onSkip`). For step-level handlers, `continue`, `stop`, `retry`, and `goToStep` are evaluated at runtime; `goToTest` is validated but not yet executed (deferred at step scope). For test-level handlers, `continue`, `stop`, and `goToTest` are evaluated at runtime (test scope; `goToTest` jumps to a test within the spec), while `retry` and `goToStep` are not applicable at test scope.
+ */
+export type Routing78 = {
+    [k: string]: unknown;
+};
+/**
+ * A single dynamic-routing entry: an optional condition (`if`) plus exactly one routing action. Attached to a step or test handler (`onPass`, `onFail`, `onWarning`, `onSkip`). For step-level handlers, `continue`, `stop`, `retry`, and `goToStep` are evaluated at runtime; `goToTest` is validated but not yet executed (deferred at step scope). For test-level handlers, `continue`, `stop`, and `goToTest` are evaluated at runtime (test scope; `goToTest` jumps to a test within the spec), while `retry` and `goToStep` are not applicable at test scope.
+ */
+export type Routing79 = {
+    [k: string]: unknown;
+};
 /**
  * Pause (in milliseconds) before performing the next action.
  */
@@ -4810,6 +4934,334 @@ export interface SourceLocation18 {
      */
     endIndex: number;
 }
+export interface Swipe {
+    swipe: Swipe1;
+    [k: string]: unknown;
+}
+export interface SwipeDirectional {
+    direction: SwipeSimple1;
+    /**
+     * How far to swipe, as a fraction of the surface's height (for up/down) or width (for left/right).
+     */
+    distance?: number;
+    /**
+     * Duration of the swipe movement in milliseconds.
+     */
+    duration?: number;
+    /**
+     * The browser window/tab or app window this step acts on. Omit to act on the active tab. The targeted surface stays focused afterward. App surfaces use the object form ({ "app": … }).
+     */
+    surface?: SurfaceByBrowserEngine5 | BrowserSurface8 | AppSurface4;
+}
+export interface BrowserSurface8 {
+    /**
+     * Browser engine. Selects the browser surface with that engine (or the one named by `name`). A goTo step opens the browser if it isn't open yet; other steps require it to already be open.
+     */
+    browser: "chrome" | "firefox" | "safari" | "webkit" | "edge";
+    /**
+     * Name of the browser surface. Defaults to the engine name (the context's default browser registers under its engine). Assign distinct names to drive multiple browsers at once, including several of the same engine.
+     */
+    name?: string;
+    window?: WindowTabSelector16;
+    tab?: WindowTabSelector17;
+}
+export interface ByCriteria20 {
+    /**
+     * Name assigned when the window/tab was opened.
+     */
+    name?: string;
+    /**
+     * Index in creation order. Negative counts from the end.
+     */
+    index?: number;
+    /**
+     * Page title to match. Substring, or /regex/.
+     */
+    title?: string;
+    /**
+     * Page URL to match. Substring, or /regex/.
+     */
+    url?: string;
+}
+export interface ByCriteria21 {
+    /**
+     * Name assigned when the window/tab was opened.
+     */
+    name?: string;
+    /**
+     * Index in creation order. Negative counts from the end.
+     */
+    index?: number;
+    /**
+     * Page title to match. Substring, or /regex/.
+     */
+    title?: string;
+    /**
+     * Page URL to match. Substring, or /regex/.
+     */
+    url?: string;
+}
+export interface AppSurface4 {
+    /**
+     * Name of an app surface opened by `startSurface` (its `name`, or the default derived from the app identifier).
+     */
+    app: string;
+    window?: AppWindowSelector4;
+}
+export interface ByCriteria22 {
+    /**
+     * Assigned window name.
+     */
+    name?: string;
+    /**
+     * Index in creation order. Negative counts from the end.
+     */
+    index?: number;
+    /**
+     * Window title to match. Substring, or /regex/.
+     */
+    title?: string;
+}
+export interface SwipePointToPoint {
+    from: Point;
+    to: Point1;
+    /**
+     * Duration of the swipe movement in milliseconds.
+     */
+    duration?: number;
+    /**
+     * The browser window/tab or app window this step acts on. Omit to act on the active tab. The targeted surface stays focused afterward. App surfaces use the object form ({ "app": … }).
+     */
+    surface?: SurfaceByBrowserEngine6 | BrowserSurface9 | AppSurface5;
+}
+/**
+ * A pixel coordinate on the surface, measured from its top-left corner (0, 0).
+ */
+export interface Point {
+    /**
+     * Horizontal position in pixels from the left edge of the surface (the app window, or the browser viewport).
+     */
+    x: number;
+    /**
+     * Vertical position in pixels from the top edge of the surface (the app window, or the browser viewport).
+     */
+    y: number;
+}
+/**
+ * A pixel coordinate on the surface, measured from its top-left corner (0, 0).
+ */
+export interface Point1 {
+    /**
+     * Horizontal position in pixels from the left edge of the surface (the app window, or the browser viewport).
+     */
+    x: number;
+    /**
+     * Vertical position in pixels from the top edge of the surface (the app window, or the browser viewport).
+     */
+    y: number;
+}
+export interface BrowserSurface9 {
+    /**
+     * Browser engine. Selects the browser surface with that engine (or the one named by `name`). A goTo step opens the browser if it isn't open yet; other steps require it to already be open.
+     */
+    browser: "chrome" | "firefox" | "safari" | "webkit" | "edge";
+    /**
+     * Name of the browser surface. Defaults to the engine name (the context's default browser registers under its engine). Assign distinct names to drive multiple browsers at once, including several of the same engine.
+     */
+    name?: string;
+    window?: WindowTabSelector18;
+    tab?: WindowTabSelector19;
+}
+export interface ByCriteria23 {
+    /**
+     * Name assigned when the window/tab was opened.
+     */
+    name?: string;
+    /**
+     * Index in creation order. Negative counts from the end.
+     */
+    index?: number;
+    /**
+     * Page title to match. Substring, or /regex/.
+     */
+    title?: string;
+    /**
+     * Page URL to match. Substring, or /regex/.
+     */
+    url?: string;
+}
+export interface ByCriteria24 {
+    /**
+     * Name assigned when the window/tab was opened.
+     */
+    name?: string;
+    /**
+     * Index in creation order. Negative counts from the end.
+     */
+    index?: number;
+    /**
+     * Page title to match. Substring, or /regex/.
+     */
+    title?: string;
+    /**
+     * Page URL to match. Substring, or /regex/.
+     */
+    url?: string;
+}
+export interface AppSurface5 {
+    /**
+     * Name of an app surface opened by `startSurface` (its `name`, or the default derived from the app identifier).
+     */
+    app: string;
+    window?: AppWindowSelector5;
+}
+export interface ByCriteria25 {
+    /**
+     * Assigned window name.
+     */
+    name?: string;
+    /**
+     * Index in creation order. Negative counts from the end.
+     */
+    index?: number;
+    /**
+     * Window title to match. Substring, or /regex/.
+     */
+    title?: string;
+}
+export interface Common19 {
+    /**
+     * JSON Schema for this object.
+     */
+    $schema?: "https://raw.githubusercontent.com/doc-detective/common/refs/heads/main/dist/schemas/step_v3.schema.json";
+    /**
+     * ID of the step.
+     */
+    stepId?: string;
+    /**
+     * Description of the step.
+     */
+    description?: string;
+    /**
+     * Whether or not the step may be unsafe. Unsafe steps may perform actions that could modify the system or environment in unexpected ways. Unsafe steps are only performed within Docker containers or if unsafe steps are enabled with the `allowUnsafeSteps` config property or the `--allow-unsafe` flag.
+     */
+    unsafe?: boolean;
+    outputs?: OutputsStep19;
+    variables?: VariablesStep19;
+    /**
+     * Whether or not this step should act as a breakpoint when debugging is enabled. When `true`, execution will pause at this step when debug mode is enabled.
+     */
+    breakpoint?: boolean;
+    if?: Condition38;
+    /**
+     * Assertions for this step. As authored input, a custom condition expression (or array of expressions, combined with logical AND). In a test result, the runner replaces this with the array of articulated assertion records it evaluated (implicit then custom).
+     */
+    assertions?: Condition39 | Assertion19[];
+    /**
+     * Routing entries evaluated when this step passes. The first entry whose `if` matches applies. `continue`, `stop`, `retry`, and `goToStep` are honored at runtime; `goToTest` is validated but not yet executed.
+     */
+    onPass?: Routing76[];
+    /**
+     * Routing entries evaluated when this step fails. The first entry whose `if` matches applies; the default when none is set stops the test. `continue`, `stop`, `retry`, and `goToStep` are honored at runtime; `goToTest` is validated but not yet executed.
+     */
+    onFail?: Routing77[];
+    /**
+     * Routing entries evaluated when this step produces a warning. The first entry whose `if` matches applies. `continue`, `stop`, `retry`, and `goToStep` are honored at runtime; `goToTest` is validated but not yet executed.
+     */
+    onWarning?: Routing78[];
+    /**
+     * Routing entries evaluated when this step is skipped (reached but not run — unsafe-blocked or guard-`if` false). The first entry whose `if` matches applies. `continue`, `stop`, and `goToStep` are honored at runtime; `goToTest` is validated but not yet executed. (`retry` is a no-op here — a step that never ran cannot be re-run.)
+     */
+    onSkip?: Routing79[];
+    location?: SourceLocation19;
+    /**
+     * Path, relative to the run's artifact directory (the report's `runDir`), of the screenshot captured automatically after this step. Always a non-empty, forward-slash, relative path. Present only in test results, when `autoScreenshot` is enabled and the capture succeeded. This is system-populated metadata and should not be set manually.
+     */
+    autoScreenshot?: string;
+    /**
+     * Total number of times this step ran (the initial attempt plus retries) when a routing `retry` action re-ran it. Present only in test results, and only when the step was retried at least once (so the value is always >= 2). This is system-populated metadata and should not be set manually.
+     */
+    attempts?: number;
+    /**
+     * Which visit of this step produced this report, when a routing goToStep re-ran it (the first visit omits this field). Present only in test results; system-populated.
+     */
+    visit?: number;
+    [k: string]: unknown;
+}
+/**
+ * Outputs from step processes and user-defined expressions. Use the `outputs` object to reference outputs in subsequent steps. If a user-defined output matches the key for a step-defined output, the user-defined output takes precedence.
+ */
+export interface OutputsStep19 {
+    /**
+     * Runtime expression for a user-defined output value.
+     *
+     * This interface was referenced by `OutputsStep19`'s JSON-Schema definition
+     * via the `patternProperty` "^[A-Za-z0-9_]+$".
+     */
+    [k: string]: string;
+}
+/**
+ * Environment variables to set from user-defined expressions.
+ */
+export interface VariablesStep19 {
+    /**
+     * Runtime expression for a user-defined output value.
+     *
+     * This interface was referenced by `VariablesStep19`'s JSON-Schema definition
+     * via the `patternProperty` "^[A-Za-z0-9_]+$".
+     */
+    [k: string]: string;
+}
+/**
+ * An articulated assertion record produced by the runner for a step result. Each record names a single verification check, whether it passed, and the values it compared. The step's result is the roll-up of its assertion results (FAIL > WARNING > all-SKIPPED > PASS). System-populated; appears in test results, not in authored specs.
+ */
+export interface Assertion19 {
+    /**
+     * Human-readable articulation of the check, e.g. `exitCode in [0]`.
+     */
+    statement: string;
+    /**
+     * Who defined the assertion: `implicit` (runner-defined) or `custom` (user-defined).
+     */
+    source: "implicit" | "custom";
+    /**
+     * Outcome of evaluating the assertion.
+     */
+    result: "PASS" | "FAIL" | "WARNING" | "SKIPPED";
+    /**
+     * The value (or values) the assertion expected. Optional.
+     */
+    expected?: unknown[] | boolean | number | null | {
+        [k: string]: unknown;
+    } | string;
+    /**
+     * The value actually observed. Optional.
+     */
+    actual?: unknown[] | boolean | number | null | {
+        [k: string]: unknown;
+    } | string;
+    /**
+     * Human-readable explanation of the outcome. Optional.
+     */
+    description?: string;
+}
+/**
+ * Source location where this step was detected in the original file. This is system-populated metadata and should not be set manually.
+ */
+export interface SourceLocation19 {
+    /**
+     * 1-indexed line number in the source file where the step was detected.
+     */
+    line: number;
+    /**
+     * 0-indexed character offset from the start of the source file where the step begins.
+     */
+    startIndex: number;
+    /**
+     * 0-indexed character offset from the start of the source file where the step ends (exclusive).
+     */
+    endIndex: number;
+}
 export interface Wait {
     wait: Wait1;
     [k: string]: unknown;