Skip to main content

hitspec validate

Validate .http and .hitspec files for syntax errors without executing them.

Arguments

Flags

Behavior

The validate command parses each file without running it. Findings are either errors or warnings. Errors are constructs that would give a wrong result, or that hitspec run refuses. They are reported with file:line:column and the command exits with code 2 (the same code run uses for a file that fails to load):
  • An unknown assertion operator (contians, =, ===, equals), with a “did you mean” hint
  • An operator without a value, or extra values (expect status 200 201)
  • A misspelt expect, block type (>>>captur) or type name, and lines inside >>> or >>>capture blocks that are not assertions or captures
  • Invalid matches regular expressions, and @auth problems
  • Unclosed >>> blocks, and blocks that are not inside a request
  • Duplicate request names, and circular @depends
  • An empty file or a request without a URL
Warnings are constructs that are probably mistakes but may be intentional. They are printed under the file’s OK line and do not change the exit code:
  • An unknown # @directive (a typo such as # @tag instead of # @tags). Custom directives start with x- (# @x-owner); @contract.* is also accepted
  • An invalid @timeout, @retry, @retryDelay or @retryOn value
  • # @directive lines at the top of a file that lead into no request
  • A @depends on a request that does not exist in the file
  • A capture path containing spaces (it can never match)
  • An unknown key in hitspec.yaml (for example tiemout), with a “did you mean” hint. validate checks the nearest hitspec.yaml from the working directory upward and lists it before the test files
With --strict, every warning is an error (exit code 2), including an unknown hitspec.yaml key, and validate additionally checks variables:
  • {{name}} must be defined in the file (@name = ...), by a >>>capture block, in an environments: entry of the nearest hitspec.yaml, in a .env file next to the file or in the working directory, or in the process environment. {{$uuid()}}, {{$env(NAME)}} and other built-ins are never flagged.
  • {{request.capture}} must name a capture that request has, and the using request should # @depends on it.
Variable checking is a static check. It cannot know which environment a later hitspec run --env selects or what a CI job injects, so it accepts a name defined in any environment and in the current process environment. That is why it is only enabled by --strict.
If all files are valid, each is printed as OK <file>. If any file has errors, the command prints each error and exits with code 2. A hitspec.yaml that cannot be parsed stops validate with exit code 3 (a configuration error) and a file:line message.

Examples

Sample Output

Use in CI/CD

hitspec list

List all requests defined in .http and .hitspec files.

Arguments

Behavior

The list command parses each file and prints each request with its name and tags. If a request has no @name annotation, the method and URL are used as the display name.

Examples

Sample Output

Use Cases

  • Discover available tests in a project
  • Verify request names before filtering with --name
  • Audit tag coverage across test files
  • Quick inventory of API endpoints under test
Last modified on October 19, 2026