API testing library, by .http files, Automatic assertion
npm install @iyulab/http-test@name directive
$guid, $timestamp, $randomInt, $datetime, etc.
bash
npm install -g @iyulab/http-test
`
Usage
`bash
http-test tests.http
http-test tests.http --verbose
http-test tests.http --var variables.json
`
Writing Tests
http-test uses a simple syntax for defining API tests in .http files.
$3
`http
$3
GET {{host}}/users
`
$3
Check the status code of the response:
`http
$3
GET {{host}}/users
#### Assert: Check status code
Status: 200
`
Status range assertions are also supported:
`http
#### Assert: Check 2xx status
Status: 2xx
`
$3
Assert response headers:
`http
$3
GET {{host}}/users
#### Assert: Check headers
Status: 200
Content-Type: application/json
`
$3
Use JSONPath to assert specific values in the response body:
`http
$3
GET {{host}}/users
#### Assert: Check response body
Status: 200
$.length: 10
$[0].id: 1
$[0].name: John Doe
`
$3
Save values from the response to use in subsequent requests:
`http
$3
POST {{host}}/users
Content-Type: application/json
{
"name": "Alice Johnson",
"email": "alice@example.com"
}
#### Assert: Check new user creation
Status: 201
$.name: Alice Johnson
Save new user ID to variable
@newUserId = $.id
`
$3
Use @name directive to reference responses from previous requests:
`http
$3
@name createUser
POST {{host}}/users
Content-Type: application/json
{
"name": "Test User"
}
###
$3
GET {{host}}/users/{{createUser.response.body.id}}
#### Assert
Status: 200
$.name: Test User
`
Available reference paths:
- {{requestName.response.body}} - Full response body
- {{requestName.response.body.field}} - Specific field from body
- {{requestName.response.status}} - Response status code
- {{requestName.response.headers.header-name}} - Response header
$3
Built-in dynamic variables:
| Variable | Description | Example |
|----------|-------------|---------|
| $guid / $uuid | Random UUID v4 | 550e8400-e29b-41d4-a716-446655440000 |
| $timestamp | Unix timestamp | 1699876543 |
| $randomInt | Random integer (0-1000) | 42 |
| $randomInt min max | Random integer in range | {{$randomInt 1 100}} |
| $datetime | ISO8601 datetime | 2024-01-15T10:30:00Z |
| $datetime format | Custom format | {{$datetime rfc1123}} |
| $localDatetime | Local datetime | 2024-01-15T10:30:00 |
| $dotenv NAME | Value from .env file | {{$dotenv API_KEY}} |
| $processEnv NAME | Environment variable | {{$processEnv NODE_ENV}} |
$3
JavaScript functions for complex validations:
`javascript
// validation.js
module.exports = function(response, context) {
const body = response.data;
const variables = context.variables;
if (!body.email.includes('@')) {
throw new Error("Invalid email format");
}
return true;
};
`
Usage in .http files:
`http
$3
GET {{host}}/users/{{newUserId}}
#### Assert: Validate response
Status: 200
_CustomAssert: ./validation.js
`
$3
Test file uploads using multipart/form-data:
`http
$3
POST {{host}}/upload
Content-Type: multipart/form-data; boundary=---boundary
Content-Disposition: form-data; name="file"; filename="example.txt"
This is the content of the file.
`
$3
Load request body from external file:
`http
$3
POST {{host}}/api/data
Content-Type: application/json
< ./data/request-body.json
`
$3
External variable file (variables.json):
`json
{
"host": "http://localhost:3000",
"apiKey": "your-api-key"
}
`
Usage:
`bash
http-test tests.http --var variables.json
`
Or inline in .http files:
`http
@host = http://localhost:3000
@apiKey = your-api-key
$3
GET {{host}}/users
Authorization: Bearer {{apiKey}}
`
$3
Test error scenarios with @expectError:
`http
$3
@expectError
GET {{host}}/nonexistent
#### Assert
Status: 404
`
Configuration
Create http-test.config.json for custom settings:
`json
{
"timeout": 30000,
"retry": 3,
"verbose": false
}
`
API Usage
Use as a library in your Node.js applications:
`typescript
import { TestManager, VariableManager, HttpFileParser } from '@iyulab/http-test';
const variableManager = new VariableManager();
variableManager.setVariable('host', 'http://localhost:3000');
const parser = new HttpFileParser(variableManager);
const requests = await parser.parse('./tests/api.http');
const testManager = new TestManager(variableManager);
const { results, summary } = await testManager.run(requests, { verbose: true });
console.log(Passed: ${summary.passedTests}/${summary.totalTests});
`
API Reference
$3
| Type | Syntax | Example |
|------|--------|---------|
| Status | Status: | Status: 200, Status: 2xx |
| Header | : | Content-Type: application/json |
| Body | $.: | $.id: 123, $[0].name: John |
| Custom | _CustomAssert: | _CustomAssert: ./validator.js |
$3
| Type | Syntax | Description |
|------|--------|-------------|
| Static | @name = value | Define variable |
| Reference | {{name}} | Use variable |
| Response | @var = $.path | Extract from response |
| Dynamic | {{$guid}} | Built-in dynamic variable |
| Named | {{req.response.body.id}}` | Reference named request |
License
MIT