Collections & Variables

Overload uses Postman Collections natively. Learn how the parser works and how to harness the power of dynamic variables.

Postman Collection Support

Overload's parser is designed to read Postman Collections directly. It supports both v2.0.0 and v2.1.0 schema versions. When reading a collection, Overload intelligently flattens nested folder structures while preserving the folder path and inheriting authentication from parent folders.

Supported Features:

Nested folders with recursive flattening
All HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
Headers (automatically ignores disabled headers)
Query parameters (both URL strings and explicit query objects)
Body types: raw (JSON, XML, text, HTML, JavaScript), form-data (text + file), urlencoded, GraphQL
Authentication: bearer, basic, apikey, oauth2
Collection variables
URL reconstruction from Postman URL objects (protocol + host + path)

Exporting from Postman

To use your API requests in Overload, you need to export them from the Postman app:

Open the Postman app.
Find your collection in the sidebar.
Click the three dots (...) next to the collection name.
Select Export.
Choose Collection v2.1 (this is required).
Click Export and save the .json file to your working directory.

Variable System

Variables allow you to reuse values across your requests and inject dynamic data. Variables use the {{variable_name}} syntax.

Three-Scope Resolution Priority:

When Overload resolves a variable, it checks scopes in the following order of priority (highest first):

Runtime Overrides: Variables passed via the CLI (--var).
Environment File: Variables loaded from a Postman environment file.
Collection Variables: Variables defined within the collection itself.

Recursive Resolution: If a resolved variable value contains another variable (e.g., {{base_url}}/api), Overload will recursively resolve it.

Dynamic Variables

Overload supports Postman's dynamic variables, allowing you to generate random data on the fly. This is essential for load testing to prevent cache hits and simulate real-world variance.

Variable	Output Description	Example Output
`{{$randomInt}}`	Random integer between 0 and 1000	`402`
`{{$timestamp}}`	Current Unix timestamp (seconds)	`1717081523`
`{{$guid}}`	A random UUID v4 string	`c0f3d4c6-...`
`{{$randomBoolean}}`	"true" or "false" string	`"true"`
`{{$randomColor}}`	A random CSS color name	`"purple"`
`{{$randomFirstName}}`	A random first name	`"Alice"`
`{{$randomEmail}}`	A random email address	`"user123@example.com"`

Environment Files

You can manage variables using Postman Environment files. Export an environment from Postman just like you export a collection.

Load the environment file via the CLI:

overload run --collection api.json --environment dev_env.json

Note: Overload only loads variables that are marked as "enabled" in the environment file.

Runtime Variable Overrides

The most powerful way to control your tests is via runtime variable overrides. The --var flag has the highest priority and can override both collection and environment variables.

overload run --collection api.json \
  --var base_url=https://staging.api.com \
  --var api_key=secret_123

This approach is highly recommended for CI/CD pipelines, allowing you to inject secrets without storing them in files.

Variable Resolution in Requests

Overload resolves variables in almost every part of the HTTP request:

URLs: {{base_url}}/api/users/{{$guid}}
Headers: Authorization: Bearer {{token}}
Body Content: JSON payloads containing {"email": "{{$randomEmail}}"}
Query Parameters: Both keys and values are resolved.