Best Practices

Organise Workflows by Domain

Group related workflows in a directory structure:

tests/
├── auth/
│   ├── login.yaml
│   ├── registration.yaml
│   └── password-reset.yaml
├── api/
│   ├── crud-users.yaml
│   └── pagination.yaml
└── db/
    ├── seed.yaml
    └── migrations.yaml

Run all tests in parallel:

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

Use Config Profiles for Environments

Never hard-code environment URLs or credentials:

# replay.yaml
profiles:
  dev:
    config:
      http:
        base_url: http://localhost:3000
      postgres:
        dsn: postgres://dev:pass@localhost:5433/devdb
  staging:
    config:
      http:
        base_url: https://staging.example.com
      postgres:
        dsn: postgres://deploy:pass@staging-db:5432/stagingdb

replay run tests/ --profile staging

Extract Early, Assert Often

Extract values as soon as they become available and assert at every meaningful checkpoint:

- name: login
  type: http
  request:
    method: POST
    url: /auth/login
  extract:
    token: $.data.token
  assert:
    - ["$.status", "eq", 200]
    - ["$.data.token", "not_null"]

- name: get-profile
  type: http
  request:
    method: GET
    url: /profile
    headers:
      Authorization: Bearer {{ token }}
  assert:
    - ["$.data.email", "not_null"]
    - ["$.data.verified", "eq", true]

This makes failures easy to pinpoint — you know exactly which step broke.

Keep Steps Focused

Each step should do one thing well. Avoid steps with multiple responsibilities:

# Good
- name: create-user
  type: http
  request:
    method: POST
    url: /users
    body:
      email: test@example.com

- name: verify-user-in-db
  type: db
  query: "SELECT id FROM users WHERE email = 'test@example.com'"
  assert:
    - ["$[0].id", "not_null"]

# Bad — mixing concerns in one step
- name: create-and-verify
  type: http
  request:
    method: POST
    url: /users
    body:
      email: test@example.com

Use Deterministic Data

Avoid random values that make tests flaky. When you need unique data, use {{ nowUnix }} or a counter:

- name: create-user
  type: http
  request:
    method: POST
    url: /users
    body:
      email: "qa-{{ nowUnix }}@example.com"

Use `ignore_error` Sparingly

ignore_error is useful for cleanup steps or optional checks, but overusing it hides real failures:

# Good — cleanup that should not fail the pipeline
- name: cleanup
  type: shell
  command: "rm -rf /tmp/test-data"
  ignore_error: true

# Avoid — this hides a real test failure
- name: critical-check
  type: http
  request:
    method: GET
    url: /health
  assert:
    - ["$.status", "eq", 200]
  ignore_error: true  # ← hides failures!

Template Sensitive Data

Use variables for secrets and credentials:

- name: login
  type: http
  request:
    method: POST
    url: /auth/login
    body:
      email: "{{ API_USERNAME }}"
      password: "{{ API_PASSWORD }}"

Pass them via environment variables or the config file — never hard-code them in workflow files.

Clean Up Test Data

When your workflow creates data, clean it up afterward:

- name: create-test-data
  type: http
  request:
    method: POST
    url: /users
  extract:
    test_user_id: $.data.id

# ... test logic ...

- name: delete-test-data
  type: http
  request:
    method: DELETE
    url: /users/{{ test_user_id }}
  ignore_error: true

Use `call` for Reusable Steps

Extract common patterns (auth, setup, teardown) into reusable files:

# auth.yaml
name: login
steps:
  - name: login
    type: http
    request:
      method: POST
      url: /auth/login
      body:
        email: "{{ email }}"
        password: "{{ password }}"
    extract:
      token: $.data.token
    returns: [token]

# test.yaml
steps:
  - name: authenticate
    type: call
    file: auth.yaml
    with:
      email: admin@example.com
      password: "{{ ADMIN_PASSWORD }}"
    returns: [token]

Version Your Workflows with the Schema

Add the JSON schema reference to get IDE autocomplete:

# yaml-language-server: $schema=https://raw.githubusercontent.com/tomiwa-a/replay/main/schema.json

Run Workflows in CI with `--fail-fast`

In CI, --fail-fast saves time by stopping at the first failure:

replay run tests/ --concurrency 4 --fail-fast

What’s Next?

Review the CLI reference
Learn about configuration
See troubleshooting for common issues

Documentation Index

​Best Practices

​Organise Workflows by Domain

​Use Config Profiles for Environments

​Extract Early, Assert Often

​Keep Steps Focused

​Use Deterministic Data

​Use ignore_error Sparingly

​Template Sensitive Data

​Clean Up Test Data

​Use call for Reusable Steps

​Version Your Workflows with the Schema

​Run Workflows in CI with --fail-fast

​What’s Next?