Skip to content
Documentation

Collection Examples

Learn how to organize multiple HTTP requests into collections with curl-runner: shared variables, defaults, validation, and complete API test suites.

Learn how to organize multiple requests into collections for comprehensive API testing.

Overview

Collections allow you to group related HTTP requests together, share variables and defaults, and run comprehensive test suites. They're perfect for testing complete API workflows or organizing tests by feature.

  • Group Related Tests (organization): organize requests by feature, endpoint, or workflow.
  • Share Configuration (reusability): define variables and defaults once, use everywhere.

Basic Collection

A simple collection groups related requests under a name and description.

basic-collection.yaml
# Basic collection structure
collection:
  name: User Management API Tests
  description: Testing user CRUD operations

  requests:
    - name: List All Users
      url: https://api.example.com/users
      method: GET

    - name: Get Specific User
      url: https://api.example.com/users/1
      method: GET

    - name: Create New User
      url: https://api.example.com/users
      method: POST
      headers:
        Content-Type: application/json
      body:
        name: "John Doe"
        email: "john@example.com"

Collection Variables

Define variables at the collection level to share across all requests. Variables are used as written: a value cannot reference another variable. Reference them with ${NAME} in the request fields.

collection-variables.yaml
# Collection with shared variables
collection:
  name: E-Commerce API Tests
  variables:
    BASE_URL: https://api.example.com
    USER_ID: 12345
    PRODUCT_ID: 98765

  requests:
    - name: Get User Profile
      url: ${BASE_URL}/users/${USER_ID}
      method: GET
      headers:
        Authorization: Bearer ${API_TOKEN}   # from the environment

    - name: Get User Orders
      url: ${BASE_URL}/users/${USER_ID}/orders
      method: GET
      headers:
        Authorization: Bearer ${API_TOKEN}

    - name: Get Product Details
      url: ${BASE_URL}/products/${PRODUCT_ID}
      method: GET

    - name: Add Product to Cart
      url: ${BASE_URL}/users/${USER_ID}/cart
      method: POST
      headers:
        Authorization: Bearer ${API_TOKEN}
        Content-Type: application/json
      body:
        productId: ${PRODUCT_ID}
        quantity: 2

Variable precedence: collection variables override global variables, and both are used before environment variables.

Complete Collection Example

A comprehensive example showing collection features including global settings, defaults, variables, and validation.

complete-collection.yaml
# Complete collection with global settings
global:
  execution: sequential
  continueOnError: true
  variables:
    BASE_URL: https://jsonplaceholder.typicode.com
  output:
    verbose: true
    showMetrics: true
    saveToFile: test-results.json

collection:
  name: JSONPlaceholder Complete Test Suite
  description: Comprehensive API testing example

  variables:
    TEST_USER_ID: 1
    TEST_POST_ID: 1

  defaults:
    timeout: 5000
    retry:
      count: 2
      delay: 1000
    headers:
      Accept: application/json
      X-API-Version: v1

  requests:
    # User Operations
    - name: Get All Users
      url: ${BASE_URL}/users
      method: GET
      expect:
        status: 200

    - name: Get Test User
      url: ${BASE_URL}/users/${TEST_USER_ID}
      method: GET
      expect:
        status: 200
        body:
          id: 1

    # Post Operations
    - name: Get User Posts
      url: ${BASE_URL}/users/${TEST_USER_ID}/posts
      method: GET
      expect:
        status: 200

    - name: Create New Post
      url: ${BASE_URL}/posts
      method: POST
      headers:
        Content-Type: application/json
      body:
        title: "Test Post"
        body: "This is a test post created by curl-runner"
        userId: ${TEST_USER_ID}
      expect:
        status: 201
        body:
          userId: 1

    - name: Update Post
      url: ${BASE_URL}/posts/${TEST_POST_ID}
      method: PUT
      body:
        id: ${TEST_POST_ID}
        title: "Updated Post"
        body: "This post has been updated"
        userId: ${TEST_USER_ID}
      expect:
        status: 200

    - name: Delete Post
      url: ${BASE_URL}/posts/${TEST_POST_ID}
      method: DELETE
      expect:
        status: 200

    # Comment Operations
    - name: Get Post Comments
      url: ${BASE_URL}/posts/${TEST_POST_ID}/comments
      method: GET
      expect:
        status: 200

    # Album Operations
    - name: Get User Albums
      url: ${BASE_URL}/users/${TEST_USER_ID}/albums
      method: GET
      expect:
        status: 200

    # Todo Operations
    - name: Get User Todos
      url: ${BASE_URL}/users/${TEST_USER_ID}/todos
      method: GET
      expect:
        status: 200

Collection Structure

Understanding the collection configuration options.

FieldTypeDescription
namestringCollection name
descriptionstringCollection description (optional)
variablesobjectCollection-level variables
defaultsobjectDefault request configuration applied to every request in the collection
requestsarrayList of requests

Multiple Collections

A YAML file holds one document, so define each collection in its own file and run them together by passing a directory (or several files). Share settings by repeating the small global block, or by putting them in a curl-runner.yaml.

auth-suite.yaml
# First collection: authentication tests
global:
  variables:
    API_URL: https://api.example.com

collection:
  name: Authentication Suite
  requests:
    - name: Login
      url: ${API_URL}/auth/login
      method: POST
      body:
        username: "testuser"
        password: "testpass"
      expect:
        status: 200
        body:
          token: "*"
      store:
        token: body.token

    - name: Refresh Token
      url: ${API_URL}/auth/refresh
      method: POST
      headers:
        Authorization: Bearer ${store.token}
      expect:
        status: 200
user-suite.yaml
# Second collection: user management tests
global:
  variables:
    API_URL: https://api.example.com

collection:
  name: User Management Suite
  defaults:
    headers:
      Accept: application/json

  requests:
    - name: Get Profile
      url: ${API_URL}/profile
      method: GET
      headers:
        Authorization: Bearer ${USER_TOKEN}
      expect:
        status: 200

    - name: Update Profile
      url: ${API_URL}/profile
      method: PATCH
      headers:
        Authorization: Bearer ${USER_TOKEN}
      body:
        displayName: "Updated Name"
      expect:
        status: 200

Running Collections

Execute collection tests using the curl-runner CLI.

terminal
# Run a collection
curl-runner collection.yaml

# Run every YAML file in a directory
curl-runner tests/

# Run with a specific output format
curl-runner collection.yaml --output-format pretty

# Run in parallel mode
curl-runner collection.yaml -p

# Save results to a file
curl-runner collection.yaml --output results.json

# Run with verbose output
curl-runner collection.yaml --verbose

Best Practices

  • Organize by feature (organization): group related endpoints together for better organization and maintainability: user management (CRUD), authentication and authorization flows, product catalog operations, payment and order processing.
  • Use descriptive names (naming): clear, meaningful names make collections and requests self-documenting. Prefer "User Registration Flow" or "Payment Processing Suite" over "test1", "test2", "temp".
  • Leverage defaults (configuration): set common configuration once at the collection level.
  • Validation and documentation (quality): validate status codes and body content, comment variable purposes and values, and set retry policies and timeouts.

Common Use Cases

  • API test suites (testing): comprehensive testing of all API endpoints with organized test cases and validation rules.
  • CI/CD pipelines (integration): automated API testing in deployment workflows for continuous integration and delivery.
  • Health checks (monitoring): regular API availability and performance monitoring with automated alerts.
  • API documentation (development): living documentation of API usage patterns and examples for development teams.