Hooks

Hooks let you run shell scripts before and after individual requests. Use @before for setup (seeding data, starting services) and @after for cleanup (removing test data, stopping services).

Security

Hooks execute shell scripts on your system. You must pass the --allow-shell flag to enable them. Without this flag, @before and @after hooks are skipped.

hitspec run tests/ --allow-shell

Basic Usage

### Test with setup and teardown
# @name testWithHooks
# @before ./scripts/setup.sh
# @after ./scripts/cleanup.sh

GET {{baseUrl}}/api/test

>>>
expect status 200
<<<

@before Hooks

@before hooks run before the HTTP request is sent. Use them to prepare test data, start services, or set up preconditions.

### Test user creation
# @name testCreateUser
# @before ./scripts/seed-db.sh
# @before ./scripts/clear-cache.sh

POST {{baseUrl}}/api/users
Content-Type: application/json

{
  "name": "Test User"
}

>>>
expect status 201
<<<

Multiple @before hooks execute in the order they are declared.

@after Hooks

@after hooks run after the request completes and assertions are evaluated. They always run, even if the request or assertions fail. This makes them reliable for cleanup.

### Test that requires cleanup
# @name testWithCleanup
# @after ./scripts/remove-test-data.sh
# @after ./scripts/reset-state.sh

DELETE {{baseUrl}}/api/test-resources/123

>>>
expect status 204
<<<

Multiple @after hooks also execute in declaration order.

@after hooks always run, even when the request fails or assertions do not pass. This guarantees cleanup happens regardless of test outcome.

Variable Resolution

Variables are resolved in hook paths and commands:

### Dynamic hook paths
# @name envSpecificTest
# @before ./scripts/setup-{{env}}.sh
# @after ./scripts/cleanup-{{env}}.sh

GET {{baseUrl}}/api/health

>>>
expect status 200
<<<

Execution Details

Behavior	Detail
Execution engine	`sh -c` (on Windows, `sh` from Git for Windows when it is installed, otherwise `cmd /C`)
Working directory	Location of the `.http` file
Multiple hooks	Executed in declaration order
`@before` failure	Request is not sent; `@after` hooks still run
`@after` timing	Always runs, even on request failure
Variable support	`{{variables}}` are resolved before execution

Example: Database Seed and Cleanup

### Verify user list after seeding
# @name verifyUsers
# @before ./scripts/seed-users.sh
# @after ./scripts/truncate-users.sh

GET {{baseUrl}}/api/users

>>>
expect status 200
expect body type array
expect body length > 0
<<<

scripts/seed-users.sh:

#!/bin/bash
psql $DATABASE_URL -c "INSERT INTO users (name, email) VALUES ('Test', 'test@example.com');"

scripts/truncate-users.sh:

#!/bin/bash
psql $DATABASE_URL -c "TRUNCATE TABLE users CASCADE;"

Example: Service Health Check

### Wait for service and test
# @name serviceTest
# @before ./scripts/start-service.sh
# @after ./scripts/stop-service.sh

GET http://localhost:8080/api/health

>>>
expect status 200
expect body.status == "ok"
<<<

For simple command execution after a request (without needing a separate script file), consider using shell command blocks with the >>>shell syntax instead.

Last modified on October 19, 2026

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

Security

Basic Usage

@before Hooks

@after Hooks

Variable Resolution

Execution Details

Example: Database Seed and Cleanup

Example: Service Health Check