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": "test@example.com", "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": "test@example.com" }
      }
    },
    {
      "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.}