hitspec run Run HTTP API tests defined in .http or .hitspec files.
hitspec run < file | directory > [flags]
Arguments Argument Description <file>Single .http or .hitspec file to run <directory>Directory containing test files (searched recursively)
You can pass multiple files and directories as arguments.
Flags Core Flags Flag Short Description Default Env Var --env-eEnvironment name to use devHITSPEC_ENV--env-filePath to .env file for variable interpolation HITSPEC_ENV_FILE--configPath to config file (hitspec.yaml) HITSPEC_CONFIG--name-nRun only tests matching name pattern --tags-tRun only tests with specified tags (comma-separated) HITSPEC_TAGS
Output Flags Flag Short Description Default Env Var --verbose-vVerbose output (use -vv or -vvv for more detail) false--quiet-qSuppress all output except errors falseHITSPEC_QUIET--no-colorDisable colored output falseHITSPEC_NO_COLOR--output-oOutput format: console, json, junit, tap, html consoleHITSPEC_OUTPUT--output-fileWrite output to a file instead of stdout HITSPEC_OUTPUT_FILE
Execution Flags Flag Short Description Default Env Var --bailStop on first failure falseHITSPEC_BAIL--timeoutRequest timeout (e.g., 30s, 1m, 500ms) 30sHITSPEC_TIMEOUT--dry-runParse and show what would run without executing false--parallel-pRun independent requests in parallel falseHITSPEC_PARALLEL--concurrencyMax concurrent requests when running in parallel 5HITSPEC_CONCURRENCY--watch-wWatch files for changes and re-run tests false
Network Flags Flag Short Description Default Env Var --proxyProxy URL for HTTP requests HITSPEC_PROXY--insecure-kDisable SSL certificate validation falseHITSPEC_INSECURE
Snapshot Flags Flag Description Default --update-snapshotsUpdate snapshot files instead of comparing against them false
Security Flags Flag Description Default --allow-shellAllow shell command execution (>>>shell blocks and hooks) false--allow-dbAllow database assertions (>>>db blocks) false
Coverage Flags Flag Description Default --coverageGenerate API coverage report against OpenAPI spec false--openapiPath to OpenAPI spec file for coverage analysis
Shell and database blocks are disabled by default for security. You must explicitly opt in with --allow-shell or --allow-db when your test files use these features.
Stress Testing Flags Flag Short Description Default --stressEnable stress testing mode false--duration-dStress test duration (e.g., 30s, 5m, 1h) 30s--rate-rTarget requests per second 10--vusNumber of virtual users (alternative to --rate) 0--max-vusMaximum concurrent requests 100--think-timeThink time between requests per virtual user 0s--ramp-upRamp-up time to reach target rate/VUs 0s--thresholdPass/fail thresholds (e.g., "p95<200ms,errors<0.1%") --profileLoad a stress profile from config file --no-progressDisable real-time progress display false--stress-jsonOutput stress results as JSON false
Metrics Flags Flag Description Default Env Var --metricsExport format: prometheus, datadog, json HITSPEC_METRICS--metrics-portPort for Prometheus metrics HTTP endpoint 9090HITSPEC_METRICS_PORT--metrics-fileOutput file for JSON metrics HITSPEC_METRICS_FILE--datadog-api-keyDataDog API key DD_API_KEY--datadog-siteDataDog site datadoghq.comDD_SITE--datadog-tagsComma-separated DataDog tags DD_TAGS
Notification Flags Flag Description Default Env Var --notifyNotification service: slack, teams HITSPEC_NOTIFY--notify-onWhen to notify: always, failure, success, recovery failureHITSPEC_NOTIFY_ON--slack-webhookSlack webhook URL SLACK_WEBHOOK--slack-channelSlack channel override SLACK_CHANNEL--teams-webhookMicrosoft Teams webhook URL TEAMS_WEBHOOK
Examples Basic Usage Run a single file
Run a directory
Run with a specific environment
Run specific tests by name
Run tests by tag
hitspec run tests/api.http
Filtering # Run only smoke-tagged tests hitspec run tests/ --tags smoke # Multiple tags (OR logic) hitspec run tests/ --tags smoke,critical # Filter by name pattern (glob matching) hitspec run tests/ --name "User*" hitspec run tests/ --name "*Profile" # Combine filters hitspec run tests/ --tags smoke --name "*Auth*"
Parallel Execution # Run independent requests in parallel hitspec run tests/ --parallel # Set concurrency limit hitspec run tests/ --parallel --concurrency 10
Requests with dependencies (@depends) always run sequentially. Only independent requests run in parallel. Captured variables are not shared between parallel requests.
Watch Mode # Watch files and re-run on changes hitspec run tests/ --watch # Combine with tags for focused development hitspec run tests/ --watch --tags dev
Console (default)
JSON
JUnit XML (for CI/CD)
TAP
HTML
Stress Testing Rate-based stress test
Virtual user mode
With pass/fail thresholds
Load profile from config
hitspec run api.http --stress --duration 1m --rate 100
CI/CD Integration # GitHub Actions example hitspec run tests/ \ --env staging \ --output junit \ --output-file test-results.xml \ --bail
# With notifications on failure hitspec run tests/ \ --env staging \ --notify slack \ --slack-webhook " $SLACK_WEBHOOK " \ --notify-on failure
Snapshot Testing # First run creates snapshots in __snapshots__/ hitspec run tests/ # Update snapshots when expected changes occur hitspec run tests/ --update-snapshots
Security Flags # Allow shell blocks and database assertions hitspec run tests/ --allow-shell --allow-db # Only allow shell execution hitspec run tests/ --allow-shell
Exit Codes Code Constant Description 0ExitSuccessAll tests passed 1ExitTestFailureOne or more tests failed 2ExitParseErrorFile parsing error (invalid syntax) 3ExitConfigErrorConfiguration error 4ExitNetworkErrorNetwork or connection error 64ExitUsageErrorInvalid CLI usage
Environment Variables All flags that support environment variables are listed in the flag tables above. Environment variables are read at startup and can be overridden by explicit flags.
Common variables:
export HITSPEC_ENV = staging export HITSPEC_TIMEOUT = 60s export HITSPEC_OUTPUT = json export HITSPEC_BAIL = true export HITSPEC_PARALLEL = true export HITSPEC_CONCURRENCY = 10
