Playbook Guide

Learn how to write powerful API tests with Quadrastack playbooks.

What is a Playbook?

A playbook is a collection of YAML files that define your HTTP tests. Quadrastack automatically discovers all .yaml and .yml files in your playbook directory and combines them into a single test suite.

Playbook Objects

Your playbooks can include these object types:

1. Requests

HTTP requests with assertions to validate responses.

requests:
  get-users:
    method: GET
    url: https://api.example.com/users
    expect:
      status: 200
      body:
        $.length: "> 0"

Learn more →

2. Assertions (Compact DSL)

Our powerful inline assertion syntax for validating responses.

expect:
  status: 200
  headers:
    Content-Type: contains application/json
  body:
    $.id: exists
    $.email: matches "^\\w+@\\w+\\.\\w+$"
    $.items.length: "> 10"

Learn more →

3. Workflows

Multi-step request sequences with data passing.

workflows:
  auth-flow:
    steps:
      - request: login
        out: auth
      - request: get-profile
        # Use {{.session.auth.body.token}}

Learn more →

4. Scenarios

Group and run sets of tests with load testing support.

scenarios:
  smoke-tests:
    labelSelector: "smoke"
    loadProfile:
      concurrency: 50
      duration: "2m"

Learn more →

5. Variables

Environment-specific configuration.

vars:
  default:
    baseUrl: http://localhost:8080
  prod:
    baseUrl: https://api.example.com

Learn more →

6. HTTP Clients

Configure timeouts, retries, and connection settings.

httpClients:
  default:
    timeout: "30s"
    retryPolicy:
      maxAttempts: 3

Learn more →

7. Mocks

Define mock API servers.

mockServer:
  api-mock:
    listen: ":8080"

mocks:
  get-user:
    server: api-mock
    match:
      method: GET
      path: /users/{id}
    respond:
      - status: 200

Learn more →

8. Templating

Dynamic values with Go templates and Sprig functions.

url: "{{.vars.baseUrl}}/users/{{.session.login.body.userId}}"
headers:
  X-Request-ID: "{{uuidv4}}"
  X-Timestamp: "{{now | date \"2006-01-02\"}}"

Learn more →

File Organization

Quadrastack loads all YAML files from your playbook directory. You can organize them however you like:

Single File (Simple)

my-tests/
└── playbook.yaml    # Everything in one file

Split by Type (Recommended)

my-tests/
├── requests.yaml
├── workflows.yaml
├── scenarios.yaml
├── vars.yaml
├── http-clients.yaml
└── mocks.yaml

Split by Feature

my-tests/
├── auth/
│   ├── requests.yaml
│   └── workflows.yaml
├── users/
│   ├── requests.yaml
│   └── scenarios.yaml
└── vars.yaml

All approaches work - choose what makes sense for your project.

Quick Reference

Complete Playbook Example

# vars.yaml
vars:
  default:
    baseUrl: http://localhost:8080
    apiKey: dev-key

# http-clients.yaml
httpClients:
  default:
    timeout: "30s"

# requests.yaml
requests:
  login:
    method: POST
    url: "{{.vars.baseUrl}}/auth/login"
    labels: [auth, smoke]
    body: |
      {
        "username": "admin",
        "password": "secret"
      }
    expect:
      status: 200
      body:
        $.token: exists

  get-users:
    method: GET
    url: "{{.vars.baseUrl}}/users"
    labels: [api, smoke]
    headers:
      X-API-Key: "{{.vars.apiKey}}"
    expect:
      status: 200
      body:
        $: type array
        $.length: "> 0"

# workflows.yaml
workflows:
  auth-flow:
    steps:
      - request: login
        out: auth
      - request: get-users

# scenarios.yaml
scenarios:
  smoke-tests:
    labelSelector: "smoke"

  load-test:
    labelSelector: "api"
    loadProfile:
      concurrency: 100
      rate: 500
      duration: "5m"

Best Practices

1. Use Labels for Organization

requests:
  get-users:
    labels: [api, smoke, users]
    # ...

2. Leverage Variables for Environments

vars:
  dev:
    baseUrl: https://dev-api.example.com
  prod:
    baseUrl: https://api.example.com

3. Write Comprehensive Assertions

expect:
  status: 200
  headers:
    Content-Type: contains application/json
  body:
    $.status: "success"
    $.data: exists
    $.data.items: type array
    $.data.items.length: "> 0"

4. Use Workflows for Dependencies

workflows:
  crud-flow:
    steps:
      - request: create-user
        out: created
      - request: get-user
        # Use {{.session.created.body.id}}
      - request: update-user
      - request: delete-user