Merge pull request #13 from probitas-test/fix/timeout

Fix scenario timeout error handling and add scenario-level timeout configuration

Author: lambdalisue

packages/probitas-builder/scenario_builder.ts

@@ -161,6 +161,7 @@ class ScenarioBuilderState<
     const definition: ScenarioDefinition = Object.freeze({
       name: this.#name,
       tags: [...(this.#scenarioOptions.tags ?? [])],
+      timeout: this.#scenarioOptions.timeout,
       steps: [...this.#steps],
       origin,
     });

packages/probitas-core/types/scenario.ts

@@ -10,6 +10,7 @@ import type { StepDefinition, StepMetadata, StepOptions } from "./step.ts";
  * ```ts
  * const options: ScenarioOptions = {
  *   tags: ["api", "integration", "slow"],
+ *   timeout: 30000,
  *   stepOptions: {
  *     timeout: 60000,
  *     retry: { maxAttempts: 2, backoff: "linear" }
@@ -32,6 +33,30 @@ export interface ScenarioOptions {
    */
   readonly tags?: readonly string[];
 
+  /**
+   * Maximum time in milliseconds for the entire scenario to complete.
+   *
+   * When specified, this timeout applies to the total execution time of all
+   * steps in the scenario. If the scenario exceeds this limit, a
+   * {@linkcode ScenarioTimeoutError} is thrown.
+   *
+   * Priority: scenario timeout > RunOptions timeout
+   *
+   * @default undefined (uses RunOptions timeout if set, otherwise no timeout)
+   *
+   * @example
+   * ```ts
+   * import { scenario } from "@probitas/builder";
+   *
+   * scenario("Quick API Test", { timeout: 5000 })
+   *   .step("Call API", async () => {
+   *     // This step and all others must complete within 5 seconds total
+   *   })
+   *   .build();
+   * ```
+   */
+  readonly timeout?: number;
+
   /**
    * Default options applied to all steps in this scenario.
    *
@@ -106,6 +131,14 @@ export interface ScenarioDefinition {
    */
   readonly tags: readonly string[];
 
+  /**
+   * Maximum time in milliseconds for the entire scenario to complete.
+   *
+   * When set, overrides the RunOptions timeout for this specific scenario.
+   * When timeout occurs, a {@linkcode ScenarioTimeoutError} is thrown.
+   */
+  readonly timeout?: number;
+
   /** Ordered sequence of entries (resources → setups → steps) */
   readonly steps: readonly StepDefinition[];
 
@@ -147,6 +180,13 @@ export interface ScenarioMetadata {
    */
   readonly tags: readonly string[];
 
+  /**
+   * Maximum time in milliseconds for the entire scenario to complete.
+   *
+   * When set, overrides the RunOptions timeout for this specific scenario.
+   */
+  readonly timeout?: number;
+
   /** Entry metadata (functions omitted for serialization) */
   readonly steps: readonly StepMetadata[];
 

packages/probitas-runner/runner.ts

@@ -1,5 +1,4 @@
 import { chunk } from "@std/collections/chunk";
-import { deadline } from "@std/async/deadline";
 import type { ScenarioDefinition, StepOptions } from "@probitas/core";
 import type {
   Reporter,
@@ -11,7 +10,7 @@ import { ScenarioRunner } from "./scenario_runner.ts";
 import { toScenarioMetadata } from "./metadata.ts";
 import { timeit } from "./utils/timeit.ts";
 import { mergeSignals } from "./utils/signal.ts";
-import { ScenarioTimeoutError } from "./errors.ts";
+import { ScenarioTimeoutError, StepTimeoutError } from "./errors.ts";
 
 /**
  * Top-level test runner that orchestrates execution of multiple scenarios.
@@ -116,64 +115,40 @@ export class Runner {
     timeout: number,
     signal?: AbortSignal,
   ): Promise<ScenarioResult> {
-    try {
-      const timeoutSignal = mergeSignals(
-        signal,
-        AbortSignal.timeout(timeout),
-      );
-      const result = await timeit(() =>
-        deadline(
-          scenarioRunner.run(scenario, { signal: timeoutSignal }),
-          timeout,
-          { signal: timeoutSignal },
-        )
-      );
+    const timeoutSignal = mergeSignals(
+      signal,
+      AbortSignal.timeout(timeout),
+    );
+
+    const result = await timeit(() =>
+      scenarioRunner.run(scenario, { signal: timeoutSignal })
+    );
+
+    // Handle timeit result
+    if (result.status === "failed") {
+      // timeit itself failed (this should be rare)
+      throw result.error;
+    }
 
-      // Handle successful execution
-      if (result.status === "passed") {
-        let scenarioResult = result.value;
-
-        // Handle timeout errors from within scenario
-        if (
-          scenarioResult.status === "failed" &&
-          isTimeoutError(scenarioResult.error)
-        ) {
-          const timeoutError = new ScenarioTimeoutError(
-            scenario.name,
-            timeout,
-            result.duration,
-            { cause: scenarioResult.error },
-          );
-          scenarioResult = {
-            ...scenarioResult,
-            error: timeoutError,
-          };
-        }
-
-        return scenarioResult;
-      } else {
-        // timeit itself failed (this should be rare)
-        throw result.error;
-      }
-    } catch (error) {
-      // Catch timeout errors thrown by deadline
-      if (isTimeoutError(error)) {
-        const metadata = toScenarioMetadata(scenario);
-        return {
-          status: "failed",
-          duration: timeout,
-          metadata,
-          steps: [],
-          error: new ScenarioTimeoutError(
-            scenario.name,
-            timeout,
-            timeout,
-            { cause: error },
-          ),
-        };
-      }
-      throw error;
+    const scenarioResult = result.value;
+
+    // Check if scenario failed due to timeout
+    if (
+      scenarioResult.status === "failed" &&
+      isTimeoutError(scenarioResult.error)
+    ) {
+      return {
+        ...scenarioResult,
+        error: new ScenarioTimeoutError(
+          scenario.name,
+          timeout,
+          result.duration,
+          { cause: scenarioResult.error },
+        ),
+      };
     }
+
+    return scenarioResult;
   }
 
   async #run(
@@ -198,11 +173,13 @@ export class Runner {
           signal?.throwIfAborted();
 
           // Execute scenario with optional timeout
-          const scenarioResult = timeout > 0
+          // Priority: scenario timeout > RunOptions timeout
+          const effectiveTimeout = scenario.timeout ?? timeout;
+          const scenarioResult = effectiveTimeout > 0
             ? await this.#runWithTimeout(
               scenarioRunner,
               scenario,
-              timeout,
+              effectiveTimeout,
               signal,
             )
             : await scenarioRunner.run(scenario, { signal });
@@ -221,5 +198,8 @@ export class Runner {
 }
 
 function isTimeoutError(error: unknown): boolean {
-  return error instanceof DOMException && error.name === "TimeoutError";
+  return (
+    (error instanceof DOMException && error.name === "TimeoutError") ||
+    error instanceof StepTimeoutError
+  );
 }