Overview
Thehttpspec command executes .http or .httpspec files, running all HTTP requests sequentially within each file and validating responses against assertions.
Command Syntax
Positional Arguments
One or more paths to HTTP spec files or directories:
- Files: Must have
.httpor.httpspecextension - Directories: Recursively searches for all
.httpand.httpspecfiles - Omitted: If no arguments provided, recursively finds all spec files in the current working directory
Flags
Display help message and exit
Alias for
--helpDefault Behavior
When run without arguments, HTTPSpec automatically discovers and runs all test files:main.zig:84-87):
- Recursively walks the current working directory
- Finds files with
.httpor.httpspecextensions (case-insensitive) - Skips hidden directories (
.and..)
Examples
Run All Tests in Current Directory
Run a Single File
Run Multiple Files
Run All Tests in a Directory
.http and .httpspec files within the tests/integration/ directory.
Mix Files and Directories
Exit Codes
HTTPSpec follows standard Unix exit code conventions:Test Execution Flow
HTTPSpec processes tests with the following behavior (frommain.zig:106-158):
- Parallel File Execution: Test files run in parallel using a thread pool
- Sequential Requests: Within each file, requests execute sequentially
- Early Exit on Failure: If any assertion fails in a file, remaining requests in that file are skipped
- Memory Isolation: Each test file uses an isolated arena allocator
Requests within a single file always run sequentially, even when multiple files are tested in parallel. This ensures that variable assignments and request dependencies work correctly.
Output Format
Successful Run
Failed Assertions
Invalid Test Files
Test Categories
HTTPSpec tracks three categories of test results:- Pass: All requests executed successfully and all assertions passed
- Fail: One or more assertions failed during execution
- Invalid: File could not be parsed or requests could not be executed
Error Handling
If a positional argument is neither a valid
.http/.httpspec file nor a directory, HTTPSpec returns an InvalidPositionalArgument error.See Also
- Configuration - Configure thread pool and performance settings
- Writing Tests - Learn assertion syntax
- HTTP File Format - Understand
.httpfile structure