Skip to main content
Watch mode monitors your .http and .hitspec files for changes and automatically re-runs tests when a file is saved. This creates a fast feedback loop during API development.

Usage

Short form:

How It Works

  1. hitspec runs all matching tests once
  2. It then watches the directories containing your test files
  3. When a .http or .hitspec file is modified, tests re-run automatically
  4. Press Ctrl+C to stop watching (exit code 130)

Combining with Filters

Combine watch mode with filters for focused development:

Debouncing

hitspec debounces file change events with a 300ms delay. Rapid consecutive saves (e.g., from auto-formatting) only trigger a single test re-run.

Output in Watch Mode

Each re-run creates fresh output. For structured formats (JSON, JUnit), the formatter is re-initialized on each change so you always get complete, valid output.
With --output-file, the file is truncated and rewritten on every re-run, so it always holds exactly one complete report from the latest run (not the reports of all runs appended together). The Watching for changes... and File changed lines are written to stderr. Stdout carries only the reports, so you can pipe or redirect it without the banners:
In watch mode, filters that match no request print no requests matched ... to stderr on every run, but watch mode keeps running instead of exiting.

Config and Environment Changes

Watch mode also re-runs when hitspec.yaml (or the file given with --config) or the file given with --env-file changes. The settings are reloaded before the next pass, so a new timeout, proxy or variable takes effect without restarting. A new .http file in a watched directory is picked up too. The directories node_modules, vendor and .git are not watched. Editors that save by renaming a temp file over the original are handled. An edited .env file takes effect on the next pass: values it exported are refreshed, or unset when the file no longer defines them. Variables you set in the shell are never overwritten. With --cookies, the cookie jar is kept across re-runs. Ctrl+C stops watching and exits with code 130.
Last modified on October 19, 2026