Skip to main content
hitspec uses specific exit codes to indicate the result of a test run. These are useful for scripting and CI/CD integration.

Exit Codes

Precedence

hitspec run always runs every file it can, even when another file fails to load. When several outcomes apply, the exit code follows this order: 2 (a file could not be loaded) over 4 (a request hit a network error) over 1 (a request failed) over 64 (filters matched nothing) over 0. A run with a broken file never exits 0, so a broken file cannot hide behind green results. An interrupted run exits 130 whatever else happened.

Network errors and timeouts

Exit 4 means hitspec could not reach the server, so there is nothing to assert on: use it to tell “the API is down or unreachable” apart from “the API answered wrongly” (1). It applies only to connection-level errors. A request that connects but then exceeds @timeout or --timeout while waiting for the response is an ordinary test failure (1), and so is a response whose body breaks off part-way, because a response did arrive. Requests skipped because a dependency failed do not change the exit code on their own.

Usage in Scripts

CI/CD Usage

Most CI systems treat any non-zero exit code as failure. hitspec’s exit codes let you distinguish between test failures and infrastructure issues. A step that accepts only 0 and 1 must also handle 4 (the API could not be reached) and 130 (interrupted):
Use --bail to stop on the first failure and exit immediately with that failure’s code (1 for a failed test, 4 for a network error). Without --bail, hitspec runs all tests before exiting.
Last modified on October 19, 2026