http-test

An API testing library that executes HTTP tests written in .http files with automatic assertion capabilities.

VS Code Extension

Use the http-test VS Code Extension for integrated testing within your editor.

!VS Code Extension Screenshot

Features

- .http file support - Standard HTTP file format compatible with REST Client
- All HTTP methods - GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, CONNECT, TRACE
- Automatic assertions - Status codes, headers, response body with JSONPath
- Variable management - Dynamic variables, environment variables, named request references
- Custom assertions - JavaScript-based validation functions
- File upload testing - Multipart form data support
- Named requests - Reference responses from previous requests using @name directive
- Dynamic variables - Built-in $guid, $timestamp, $randomInt, $datetime, etc.
- Detailed reporting - Test summaries with pass/fail status

Installation

``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