Parallel Execution

Replay supports parallel execution at three levels: multi-workflow concurrency, shell command parallelism, and multi-workflow file format. This speeds up test suites and enables efficient use of CI resources.

Multi-Workflow Concurrency

Run multiple workflow files at the same time using --concurrency N:

replay run tests/*.yaml --concurrency 4

This starts a worker pool with 4 workers. Each workflow gets its own isolated state bag — no variable leakage between parallel workflows.

How It Works

Replay uses a worker pool pattern:

All workflows are loaded and queued
Up to N workers pull workflows from the queue
Each worker executes one workflow in its own goroutine
Each workflow has an independent state bag
Results are collected and reported per workflow

Safeguards

Each workflow has its own isolated state bag — no shared variables
Max concurrency is capped to prevent DB/API overload
Output stays ordered in the final summary
Supports both fail-fast and continue-on-error modes

Example

# Run everything in the tests directory, 6 at a time
replay run tests/regression/*.yaml --concurrency 6

# Run 3 specific workflows in parallel
replay run auth.yaml catalog.yaml checkout.yaml --concurrency 3

Fail-Fast

Stop execution on the first failure — saves time in CI:

replay run tests/*.yaml --concurrency 4 --fail-fast

When --fail-fast is active and any single workflow fails, remaining queued workflows are skipped and Replay exits with code 1.

Multi-Workflow Files

A single YAML file can contain multiple workflows separated by ---:

# slow-tasks.yaml
name: Slow Task A
steps:
  - name: sleep
    type: shell
    command: sleep 5
  - name: done-a
    type: print
    message: "Task A finished"

---
name: Slow Task B
steps:
  - name: sleep
    type: shell
    command: sleep 7
  - name: done-b
    type: print
    message: "Task B finished"

Run them in parallel:

replay run slow-tasks.yaml --concurrency 2

Total time is ~7s instead of ~12s.

Combining with Glob Patterns

# Concurrency across files
replay run tests/**/*.yaml --concurrency 4 --fail-fast

Each workflow in each file is treated as a unit of work for the pool.

Parallel Shell Commands

Within a single shell step, you can run multiple commands concurrently:

- name: parallel-shell
  type: shell
  parallel: true
  commands:
    - "sleep 3 && echo 'Task 1 done'"
    - "sleep 2 && echo 'Task 2 done'"
    - "sleep 1 && echo 'Task 3 done'"

All three commands start simultaneously. The step waits for all to finish before proceeding.

Output in Parallel Mode

When parallel: true, per-command outputs are stored with indexed names:

Variable	Description
`stdout_0`	Stdout of first command
`stdout_1`	Stdout of second command
`stderr_0`	Stderr of first command

extract:
  task1_result: $.stdout_0
  task2_result: $.stdout_1

The final stdout variable contains the output of the last command.

Combining All Three Levels

# full-suite.yaml
name: Auth Tests
steps:
  - name: test-login
    type: http
    request:
      method: POST
      url: /auth/login

---
name: Cache Tests
steps:
  - name: parallel-redis
    type: shell
    parallel: true
    commands:
      - "redis-cli SET k1 v1"
      - "redis-cli SET k2 v2"
      - "redis-cli SET k3 v3"

---
name: DB Tests
steps:
  - name: check-db
    type: db
    query: "SELECT count(*) as cnt FROM users"
    assert:
      - ["$[0].cnt", "gt", 0]

replay run full-suite.yaml --concurrency 3 --fail-fast

This runs all three workflows concurrently. Within the Cache Tests step, three Redis commands run in parallel.

What’s Next?

Validate outcomes with assertions
Integrate with CI/CD pipelines

Documentation Index

​Parallel Execution

​Multi-Workflow Concurrency

​How It Works

​Safeguards

​Example

​Fail-Fast

​Multi-Workflow Files

​Combining with Glob Patterns

​Parallel Shell Commands

​Output in Parallel Mode

​Combining All Three Levels

​What’s Next?