Skip to main content
Get started with HTTPSpec by creating your first integration test in just a few steps.

​
Prerequisites

Before you begin, make sure you have:
  • HTTPSpec installed on your system (see Installation)
  • A terminal or command prompt
  • An API to test (we’ll use a public API in this guide)

​
Create your first test

1

Create a test file

Create a new file called my-first-test.httpspec:
touch my-first-test.httpspec
Open it in your favorite text editor.
2

Add a test request

Add the following content to test the JSONPlaceholder API:
my-first-test.httpspec
### Test JSONPlaceholder API
GET https://jsonplaceholder.typicode.com/users/1
Accept: application/json

//# status == 200
//# body contains "Leanne Graham"
This test makes a GET request and verifies:
  • The response status is 200
  • The response body contains “Leanne Graham”
3

Run the test

Execute your test with the httpspec command:
httpspec my-first-test.httpspec
You should see output indicating the test passed:
Running test 1: my-first-test.httpspec
All 1 tests ran successfully!

Pass: 1
Fail: 0

​
Understanding test output

HTTPSpec provides clear feedback about test results:

​
Passing tests

When all assertions pass, you’ll see: 
All 1 tests ran successfully!

Pass: 1
Fail: 0

​
Failing tests

If an assertion fails, HTTPSpec shows exactly what went wrong: 
### Test with failing assertion
GET https://httpbin.org/json

//# status == 404
//# body contains "nonexistent"  
//# header["content-type"] == "text/plain"
Running this test produces: 
Running test 1: test.httpspec
[Fail] Expected status code 404, got 200
All 1 tests ran successfully!

Pass: 0
Fail: 1
HTTPSpec stops executing requests in a file after the first failure. This prevents cascading failures when tests depend on each other.

​
Multiple requests in one file

You can include multiple test requests in a single file. They execute sequentially: 
### Create a user
GET https://jsonplaceholder.typicode.com/users/1
Accept: application/json

//# status == 200

### Get user posts
GET https://jsonplaceholder.typicode.com/posts?userId=1
Accept: application/json

//# status == 200
//# body contains "posts"

### Verify user data
GET https://jsonplaceholder.typicode.com/users/1
Accept: application/json

//# status == 200
//# header["content-type"] contains "application/json"

​
Running multiple test files

You can run all tests in a directory: 
# Run all .http and .httpspec files in current directory
httpspec

# Run all tests in a specific directory
httpspec ./tests

# Run specific files
httpspec test1.httpspec test2.http

​
Common assertion patterns

Here are some frequently used assertion patterns: 
### Check for successful response
GET https://api.example.com/users

//# status == 200

### Check for created resource
POST https://api.example.com/users

//# status == 201

### Check for not found
GET https://api.example.com/missing

//# status == 404

​
Performance tuning

For faster test execution, configure parallel execution: 
# Run tests with 4 parallel threads
HTTP_THREAD_COUNT=4 httpspec ./tests
Files run in parallel, but requests within each file run sequentially. See Parallel Execution for details.

​
Real-world example

Here’s a practical example testing a REST API workflow:
api-workflow.httpspec
### Step 1: Check API health
GET https://jsonplaceholder.typicode.com/posts/1
Accept: application/json

//# status == 200
//# header["content-type"] contains "application/json"

### Step 2: Fetch user data
GET https://jsonplaceholder.typicode.com/users/1
Accept: application/json

//# status == 200
//# body contains "Leanne Graham"
//# body contains "email"

### Step 3: Get user's posts
GET https://jsonplaceholder.typicode.com/posts?userId=1
Accept: application/json

//# status == 200
//# body contains "userId"
Run it: 
httpspec api-workflow.httpspec

​
Next steps

File format

Learn the complete HTTPSpec file format

Assertion types

Explore all available assertion operators

Examples

See more practical examples

Sequential testing

Understand sequential request execution

Build docs developers (and LLMs) love

Get started for freeTalk to us