@probitas/runner

Test execution and orchestration engine for Probitas scenarios.

This package provides the ScenarioRunner class that executes scenario definitions built with @probitas/builder. It handles the complete test lifecycle including resource initialization, setup/cleanup hooks, step execution with retry logic, and result reporting.

Links

• GitHub Repository
• @probitas/probitas - Main package (recommended for most users)

Related Packages

Package	Description
@probitas/builder	Build scenario definitions to execute
@probitas/scenario	Core type definitions
@probitas/reporter	Output formatters for results
@probitas/cli	CLI that uses this runner

Key Features

• Concurrent execution: Run multiple scenarios in parallel with configurable concurrency
• Failure control: Stop after N failures or continue through all tests
• Resource lifecycle: Automatic initialization and disposal of resources
• Retry logic: Built-in retry with linear/exponential backoff strategies
• Reporter integration: Pluggable reporters for custom output formatting
• Abort support: Cancel running tests via AbortSignal

Core Exports

• ScenarioRunner - Main class for executing scenarios
• Skip - Exception class to skip scenarios conditionally
• Reporter - Interface for observing test execution events
• RunOptions - Configuration options for test runs
• RunResult - Aggregated results from a test run
• ScenarioResult - Result from executing a single scenario
• StepResult - Result from executing a single step

Error Types

• TimeoutError - Thrown when a step exceeds its timeout
• RetryExhaustedError - Thrown when all retry attempts fail

deno add jsr:@probitas/runner

class Runner

const reporter = new ListReporter();
const runner = new Runner(reporter);

const result = await runner.run(scenarios, {
  maxConcurrency: 4,
  maxFailures: 1,
});

new Runner(reporter: Reporter)

run(): unknown

class Skip extends Error

import { scenario, Skip } from "@probitas/probitas";

scenario("Production Only")
  .step("Check environment", () => {
    if (Deno.env.get("ENV") !== "production") {
      throw new Skip("Only runs in production");
    }
  })
  .step("Production test", () => { ... })
  .build();

scenario("Database Test")
  .resource("db", async () => {
    try {
      return await Database.connect();
    } catch {
      throw new Skip("Database not available");
    }
  })
  .step("Query data", (ctx) => ctx.resources.db.query(...))
  .build();

scenario("Beta Feature")
  .step("Check feature flag", (ctx) => {
    if (!ctx.store.get("betaEnabled")) {
      throw new Skip("Beta feature not enabled");
    }
  })
  .build();

new Skip(reason?: string)

interface Reporter

onRunStart(scenarios: readonly ScenarioDefinition[]): void | Promise<void>

onRunEnd(scenarios: readonly ScenarioDefinition[], result: RunResult): void | Promise<void>

onScenarioStart(scenario: ScenarioDefinition): void | Promise<void>

onScenarioEnd(scenario: ScenarioDefinition, result: ScenarioResult): void | Promise<void>

onStepStart(scenario: ScenarioDefinition, step: StepDefinition): void | Promise<void>

onStepEnd(scenario: ScenarioDefinition, step: StepDefinition, result: StepResult): void | Promise<void>

interface RunFilter

const filter: RunFilter = {
  tags: ["api", "integration"]  // Must have BOTH tags
};

const filter: RunFilter = {
  pattern: /login/i  // Name must contain "login"
};

interface RunOptions

const options: RunOptions = {
  reporter: new ListReporter(),
  maxConcurrency: 1,  // Run one at a time
  maxFailures: 1      // Stop after first failure
};

const options: RunOptions = {
  reporter: new DotReporter(),
  maxConcurrency: 4   // Run up to 4 scenarios at once
};

interface RunResult

const summary: RunResult = {
  total: 10,
  passed: 8,
  failed: 1,
  skipped: 1,
  duration: 5432,
  scenarios: [...]
};

console.log(`${summary.passed}/${summary.total} passed`);
// → "8/10 passed"

interface ScenarioContext

scenario("Context Example")
  .step("Use context", (ctx) => {
    console.log(`Running: ${ctx.name}`);
    console.log(`Tags: ${ctx.options.tags.join(", ")}`);
    console.log(`Previous results: ${ctx.results.length}`);
  })
  .build();

type ScenarioResult = { status: "passed"; metadata: ScenarioMetadata; duration: number; steps: readonly StepResult[] } | { status: "failed" | "skipped"; metadata: ScenarioMetadata; duration: number; steps: readonly StepResult[]; error: unknown }

type StepResult = { status: "passed"; metadata: StepMetadata; duration: number; value: unknown } | { status: "failed" | "skipped"; metadata: StepMetadata; duration: number; error: unknown }