req-test

File-based HTTP test runner. Define your API tests in a requests.json file and run them like a test suite. Zero dependencies.

Like Postman/Newman, but a single Node.js file you can commit to your repo.

Install

npm install -g req-test

Or without installing:

npx req-test

Quick Start

# Create a starter requests.json
req-test init

# Run the tests
req-test

# Run a specific file
req-test ./tests/api.json

# Verbose output (show all assertions)
req-test --verbose

Test File Format (requests.json)

{
  "vars": {
    "base": "http://localhost:3000",
    "token": "my-auth-token"
  },
  "timeout": 5000,
  "tests": [
    {
      "name": "Health check",
      "method": "GET",
      "url": "{{base}}/health",
      "expect": {
        "status": 200,
        "json": { "status": "ok" },
        "maxLatency": 200
      }
    },
    {
      "name": "Login and get token",
      "method": "POST",
      "url": "{{base}}/auth/login",
      "body": { "email": "[email protected]", "password": "secret" },
      "expect": { "status": 200 },
      "extract": { "authToken": "$.token" }
    },
    {
      "name": "Get protected resource",
      "method": "GET",
      "url": "{{base}}/api/profile",
      "headers": { "Authorization": "Bearer {{authToken}}" },
      "expect": {
        "status": 200,
        "jsonPath": { "$.email": "[email protected]" }
      }
    },
    {
      "name": "Unauthenticated request is rejected",
      "method": "GET",
      "url": "{{base}}/api/profile",
      "expect": { "statusRange": "4xx" },
      "skip": false
    }
  ]
}

Example Output

req-test  requests.json
  4 test(s) · base: http://localhost:3000

  ✓ Health check  200 · 12ms
  ✓ Login and get token  200 · 45ms
  ✓ Get protected resource  200 · 18ms
  ✓ Unauthenticated request is rejected  401 · 8ms

  4 passed  of 4 tests

With failures:

  ✘ Get protected resource  500 · 203ms
    ✘ status 500 != 200
    ✘ latency 203ms > 200ms

Assertions

| Assertion | Type | Description | |---|---|---| | status | number | Exact HTTP status code | | statusRange | "2xx" | "4xx" | "5xx" | Status code class | | json | object | Partial JSON match (nested ok) | | jsonPath | object | { "$.user.name": "Alice" } | | bodyContains | string | String present in response body | | bodyNotContains | string | String absent from response body | | header | object | { "content-type": "application/json" } | | maxLatency | number | Max response time in milliseconds |

Variables & Chaining

Use {{varName}} in any string field. Define vars at suite level, or extract from responses with extract:

{
  "extract": { "userId": "$.data.id" }
}

Extracted values are available in all subsequent tests as {{userId}}.

CI Integration

- name: API Tests
  run: npx req-test ./tests/integration.json

Exit code is 1 if any test fails.

License

MIT

Keywords

api testing · http test runner · postman alternative · newman alternative · rest client · api assertions · integration test · curl test · zero dependencies · ci

Built to solve, shared to help — Rushabh Shah 🛠️✨

One of 40+ zero-dependency developer CLI tools — no node_modules, ever.