@probitas/builder

Builder module for creating scenario definitions with a fluent, type-safe API.

This package provides the scenario fn function that returns a builder for constructing scenario definitions. The builder uses method chaining to define resources, setup functions, and test steps with full TypeScript type inference.

Links

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

Related Packages

Package	Description
@probitas/scenario	Core type definitions used by this builder
@probitas/runner	Executes scenarios built with this package

Key Features

• Fluent API: Chain methods naturally to build complex scenarios
• Type-safe context: Each step receives typed access to previous step results
• Resource management: Register resources with automatic lifecycle handling
• Setup/Cleanup: Define setup functions with automatic cleanup support
• Configurable defaults: Override timeout and retry settings at any level

Core Exports

• scenario - Factory function to create a new scenario builder
• StepContext - Type representing the context passed to step functions
• StepFunction - Type signature for step functions
• SetupFunction - Type signature for setup functions
• ResourceFunction - Type signature for resource fn functions
• BuilderScenarioOptions - Partial options for scenario configuration
• BuilderStepOptions - Partial options for step configuration
• DEFAULT_SCENARIO_OPTIONS - Default values for scenario options
• DEFAULT_STEP_OPTIONS - Default values for step options

deno add jsr:@probitas/builder

function scenario(name: string, options?: ScenarioOptions): ScenarioBuilderInit

import { scenario } from "@probitas/builder";

export default scenario("User Registration")
  .step("Create user", async () => {
    const user = await createUser({ email: "test@example.com" });
    return { userId: user.id };
  })
  .step("Verify email", async (ctx) => {
    // ctx.previous is typed as { userId: string }
    await verifyEmail(ctx.previous.userId);
  })
  .build();

scenario("Payment Integration", {
  tags: ["integration", "payment", "slow"],
  stepOptions: { timeout: 60000 }  // 1 minute timeout for all steps
})
  .step("Process payment", async () => { ... })
  .build();

// Run with: probitas run -s "tag:payment"

scenario("Database Test")
  .resource("db", async () => await Database.connect())
  .setup((ctx) => {
    // Run migrations
    return () => ctx.resources.db.rollback();
  })
  .step("Insert data", (ctx) => ctx.resources.db.insert(...))
  .step("Query data", (ctx) => ctx.resources.db.query(...))
  .build();

type BuilderStepContext<P = unknown, A extends readonly unknown[] = readonly unknown[], R extends Record<string, unknown> = Record<string, unknown>> = StepContext & { previous: P; results: A; resources: R }

type BuilderStepDefinition<T = unknown, P = unknown, A extends readonly unknown[] = readonly unknown[], R extends Record<string, unknown> = Record<string, unknown>> = StepDefinition & { fn: BuilderStepFunction<T, P, A, R> }

type BuilderStepFunction<T = unknown, P = unknown, A extends readonly unknown[] = readonly unknown[], R extends Record<string, unknown> = Record<string, unknown>> = (ctx: BuilderStepContext<P, A, R>) => unknown