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 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 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: 2Variable 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 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: 200Collection Structure
Understanding the collection configuration options.
| Field | Type | Description |
|---|---|---|
name | string | Collection name |
description | string | Collection description (optional) |
variables | object | Collection-level variables |
defaults | object | Default request configuration applied to every request in the collection |
requests | array | List 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.
# 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# 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: 200Running Collections
Execute collection tests using the curl-runner CLI.
# 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 --verboseBest 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.
Basic Examples
Simple curl-runner examples to get started with HTTP requests. Learn basic GET, POST, PUT, and DELETE operations with practical examples.
Advanced Examples
Complex curl-runner configurations for advanced use cases. Learn variable interpolation, authentication, validation, and real-world API testing.