# @probitas/builder

> Version: 0.5.2

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

This package provides the {@linkcode 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](https://github.com/probitas-test/probitas)
- [@probitas/probitas](https://jsr.io/@probitas/probitas) - Main package (recommended for most users)

## Related Packages

| Package | Description |
|---------|-------------|
| [@probitas/core](https://jsr.io/@probitas/core) | Core type definitions used by this builder |
| [@probitas/runner](https://jsr.io/@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

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


## Functions

### `scenario`

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

Create a new scenario builder with a fluent API.

This is the primary entry point for defining scenarios. It returns a builder
that provides a type-safe, chainable API for constructing test scenarios.


**Parameters:**

- `name`: `string` — - Human-readable scenario name (shown in test reports)
- `options`: `ScenarioOptions` (optional) — - Optional configuration for tags, timeouts, and retry behavior

**Returns:** `ScenarioBuilderInit`

New {@linkcode ScenarioBuilderInit} instance ready for chaining


**Example:**

Basic scenario with type-safe step chaining
```ts
import { scenario } from "@probitas/builder";

// Mock user service for example
const createUser = (_data: { email: string }) =>
  Promise.resolve({ id: "user-123" });
const verifyEmail = (_userId: string) => Promise.resolve();

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 with tags for filtering
```ts
import { scenario } from "@probitas/builder";

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

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

Scenario with resources and setup
```ts
import { scenario } from "@probitas/builder";

// Mock Database for example
const Database = {
  connect: () =>
    Promise.resolve({
      rollback: () => {},
      insert: (_data: { id: number }) => {},
      query: (_sql: string) => [{ id: 1 }],
    }),
};

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({ id: 1 }))
  .step("Query data", (ctx) => ctx.resources.db.query("SELECT * FROM users"))
  .build();
```

---

## Types

### `BuilderStepContext`

```typescript
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 }
```

Execution context provided to steps, resources, and setup hooks.

The context provides access to:
- Previous step results with full type inference
- All accumulated results as a typed tuple
- Named resources registered with `.resource()`
- Shared storage for cross-step communication
- Abort signal for timeout and cancellation handling


---

### `BuilderStepFunction`

```typescript
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
```

Function signature for step execution.

A step function receives the execution context and returns a value
(sync or async) that becomes available to subsequent steps.


---

### `BuilderStepDefinition`

```typescript
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> }
```

Immutable definition of a scenario step.

Contains all information needed to execute a single step:
the step function, its options, and debugging metadata.


---

## Related Links

### This Package

- [`BuilderStepContext`](https://probitas-test.github.io/documents/api/builder#BuilderStepContext)
- [`BuilderStepFunction`](https://probitas-test.github.io/documents/api/builder#BuilderStepFunction)

### Other Packages

- [`ScenarioOptions`](https://probitas-test.github.io/documents/api/scenario#ScenarioOptions) (@probitas/scenario)
- [`StepContext`](https://probitas-test.github.io/documents/api/scenario#StepContext) (@probitas/scenario)
- [`StepDefinition`](https://probitas-test.github.io/documents/api/scenario#StepDefinition) (@probitas/scenario)

### Built-in Types

- [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)

---

*Last updated: 2026-01-12*