> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ellomas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Parallel Execution

> Running multiple workflows concurrently, parallel shell commands, and multi-workflow files.

# 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`:

```bash theme={null}
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:

1. All workflows are loaded and queued
2. Up to N workers pull workflows from the queue
3. Each worker executes one workflow in its own goroutine
4. Each workflow has an independent state bag
5. 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

```bash theme={null}
# 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:

```bash theme={null}
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 `---`:

```yaml theme={null}
# 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:

```bash theme={null}
replay run slow-tasks.yaml --concurrency 2
```

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

### Combining with Glob Patterns

```bash theme={null}
# 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:

```yaml theme={null}
- 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  |

```yaml theme={null}
extract:
  task1_result: $.stdout_0
  task2_result: $.stdout_1
```

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

## Combining All Three Levels

```yaml theme={null}
# 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]
```

```bash theme={null}
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](/replay/guides/assertions)
* Integrate with [CI/CD pipelines](/replay/guides/ci-cd-integration)