Probitas

Scenario-based testing & workflow execution framework.

Features

• Scenario-Based Testing: Define test workflows as a sequence of steps with type-safe result passing
• Flexible Execution: Run scenarios in parallel or sequentially with configurable concurrency
• Multiple Reporters: Output in various formats (List, Dot, JSON, TAP)
• Resource Management: Automatic cleanup with Disposable/AsyncDisposable pattern
• Retry Logic: Built-in retry with exponential/linear backoff
• Tag-Based Filtering: Organize and run scenarios by tags

Quick Start

Installation

Using Deno

deno install -grAf -n probitas jsr:@probitas/cli

• -g Global install
• -r Reload cache (fetch latest version)
• -A All permissions
• -f Force overwrite existing
• -n probitas Command name

Using Nix

# Run without installing
nix run github:jsr-probitas/probitas

# Install into your profile
nix profile install github:jsr-probitas/probitas#probitas

The flake packages a wrapper that runs the bundled CLI with the repository import map and lockfile.

Initialize a Project

probitas init

This creates:

• deno.json - Configuration with probitas import and settings
• probitas/example.probitas.ts - Example scenario

Write Your First Scenario

Create probitas/hello.probitas.ts:

import { scenario, Skip } from "probitas";

export default scenario("Hello Probitas", { tags: ["example"] })
  .step(() => {
    // Unnamed steps are auto-named as "Step N"
    if (!Deno.env.get("RUN_EXAMPLE")) {
      throw new Skip("Example skipped");
    }
  })
  .step("Greet", () => {
    return { message: "Hello, World!" };
  })
  .step("Verify", (ctx) => {
    if (ctx.previous.message !== "Hello, World!") {
      throw new Error("Unexpected message");
    }
  })
  .build();

Run Scenarios

# Run all scenarios
probitas run

# Run scenarios with specific tag
probitas run -s tag:example

# Run with different reporter
probitas run --reporter dot

Key Concepts

Scenarios

A scenario is a sequence of steps that execute in order. Each step can:

• Return a value that's passed to the next step via ctx.previous
• Access all previous results via ctx.results
• Share state via ctx.store
• Have custom timeout and retry configuration

Resources

Lifecycle-managed objects with automatic cleanup:

scenario("Database Test")
  .resource("db", async () => {
    const conn = await Database.connect();
    return conn; // Auto-disposed after scenario
  })
  .step("Query data", (ctx) => {
    return ctx.resources.db.query("SELECT * FROM users");
  })
  .build();

Setup with Cleanup

For side effects that need cleanup:

scenario("File Test")
  .setup((ctx) => {
    const tempFile = Deno.makeTempFileSync();
    ctx.store.set("tempFile", tempFile);
    return () => Deno.removeSync(tempFile); // Cleanup function
  })
  .step("Write to file", (ctx) => {
    Deno.writeTextFileSync(ctx.store.get("tempFile") as string, "test");
  })
  .build();

Tags

Organize scenarios with tags for easy filtering:

scenario("Login Test", { tags: ["auth", "critical"] });

Run specific scenarios:

probitas run -s tag:auth
probitas run -s "tag:critical,tag:auth"  # AND logic
probitas run -s "!tag:slow"              # NOT logic

Reporters

Choose output format based on your needs:

• list - Detailed human-readable output (default)
• dot - Compact progress dots
• json - Machine-readable JSON
• tap - TAP format for CI integration

Configuration

Add to deno.json or deno.jsonc:

{
  "imports": {
    "probitas": "jsr:@probitas/probitas"
  },
  "probitas": {
    "includes": ["probitas/**/*.probitas.ts"],
    "excludes": ["**/*.skip.probitas.ts"],
    "reporter": "list",
    "maxConcurrency": 4,
    "selectors": ["!tag:wip"]
  }
}

Documentation

• Guide - Comprehensive usage guide
• CLI Reference - Command-line options
• Architecture - Design overview

Development Environment

A Nix flake is available to provision the Deno toolchain without global installs.

# Enter the development shell
nix develop

# Optional: auto-activate with direnv
echo "use flake" > .envrc
direnv allow

Run project tasks such as deno task verify from within the Nix shell for consistent tooling.

Packages

Package	JSR	Description
@probitas/probitas		Primary library for writing scenarios
@probitas/cli		Command-line interface
@probitas/builder		Type-safe scenario definition API
@probitas/runner		Scenario execution engine
@probitas/reporter		Output formatters (List, Dot, JSON, TAP)
@probitas/scenario		Scenario loading and filtering
@probitas/discover		File discovery with glob patterns

License

See LICENSE file for details.