@lowdep/req-test 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rushabh Shah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# req-test
+
+![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen) ![Node](https://img.shields.io/badge/node-%3E%3D14-blue) ![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
+
+
+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
+
+```bash
+npm install -g req-test
+```
+
+Or without installing:
+
+```bash
+npx req-test
+```
+
+---
+
+## Quick Start
+
+```bash
+# 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`)
+
+```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`:
+
+```json
+{
+  "extract": { "userId": "$.data.id" }
+}
+```
+
+Extracted values are available in all subsequent tests as `{{userId}}`.
+
+---
+
+## CI Integration
+
+```yaml
+- 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`
+
+---
+
+<div align="center">
+
+**Built to solve, shared to help — Rushabh Shah 🛠️✨**
+
+<sub>One of 40+ zero-dependency developer CLI tools — no <code>node_modules</code>, ever.</sub>
+
+</div>

package/bin/req-test.js

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+'use strict';
+
+const http  = require('http');
+const https = require('https');
+const fs    = require('fs');
+const path  = require('path');
+const url   = require('url');
+
+const VERSION  = '1.0.0';
+const CFG_FILE = 'requests.json';
+
+// ─── ANSI ─────────────────────────────────────────────────────────────────────
+const isTTY  = process.stdout.isTTY;
+const c      = (code, t) => isTTY ? `\x1b[${code}m${t}\x1b[0m` : t;
+const bold   = t => c('1',  t);
+const dim    = t => c('2',  t);
+const red    = t => c('31', t);
+const green  = t => c('32', t);
+const yellow = t => c('33', t);
+const cyan   = t => c('36', t);
+
+// ─── HTTP fetch ───────────────────────────────────────────────────────────────
+function fetchRequest(opts) {
+  return new Promise((resolve, reject) => {
+    const { method = 'GET', url: rawUrl, headers = {}, body, timeout = 10000 } = opts;
+    const parsed = new url.URL(rawUrl);
+    const lib    = parsed.protocol === 'https:' ? https : http;
+
+    const reqOpts = {
+      hostname: parsed.hostname,
+      port:     parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path:     parsed.pathname + parsed.search,
+      method:   method.toUpperCase(),
+      headers:  { 'User-Agent': `req-test/${VERSION}`, ...headers },
+    };
+
+    let bodyStr = '';
+    if (body) {
+      bodyStr = typeof body === 'string' ? body : JSON.stringify(body);
+      if (!reqOpts.headers['Content-Type']) reqOpts.headers['Content-Type'] = 'application/json';
+      reqOpts.headers['Content-Length'] = Buffer.byteLength(bodyStr);
+    }
+
+    const start = Date.now();
+    const req = lib.request(reqOpts, res => {
+      let raw = '';
+      res.setEncoding('utf8');
+      res.on('data', d => { raw += d; });
+      res.on('end', () => {
+        let json = null;
+        try { json = JSON.parse(raw); } catch {}
+        resolve({ status: res.statusCode, headers: res.headers, body: raw, json, latency: Date.now() - start });
+      });
+    });
+
+    req.setTimeout(timeout, () => { req.destroy(); reject(new Error(`Timeout after ${timeout}ms`)); });
+    req.on('error', reject);
+    if (bodyStr) req.write(bodyStr);
+    req.end();
+  });
+}
+
+// ─── Assertions ───────────────────────────────────────────────────────────────
+// Returns array of { pass, message }
+function runAssertions(expect, response) {
+  const results = [];
+
+  // Status
+  if (expect.status !== undefined) {
+    const pass = response.status === expect.status;
+    results.push({ pass, message: `status ${response.status} ${pass ? '==' : '!='} ${expect.status}` });
+  }
+
+  // Status range: "2xx", "4xx"
+  if (expect.statusRange) {
+    const code  = String(response.status)[0];
+    const range = String(expect.statusRange)[0];
+    const pass  = code === range;
+    results.push({ pass, message: `status ${response.status} ${pass ? 'is' : 'is not'} ${expect.statusRange}` });
+  }
+
+  // Body contains string
+  if (expect.bodyContains !== undefined) {
+    const pass = response.body.includes(String(expect.bodyContains));
+    results.push({ pass, message: `body ${pass ? 'contains' : 'does not contain'} "${expect.bodyContains}"` });
+  }
+
+  // Body does not contain
+  if (expect.bodyNotContains !== undefined) {
+    const pass = !response.body.includes(String(expect.bodyNotContains));
+    results.push({ pass, message: `body ${pass ? 'does not contain' : 'contains'} "${expect.bodyNotContains}"` });
+  }
+
+  // JSON deep partial match
+  if (expect.json !== undefined) {
+    const { pass, msg } = jsonPartialMatch(response.json, expect.json, '');
+    results.push({ pass, message: msg });
+  }
+
+  // JSON path assertions: { "$.user.name": "Alice" }
+  if (expect.jsonPath) {
+    for (const [jsonPath, expected] of Object.entries(expect.jsonPath)) {
+      const actual = getJsonPath(response.json, jsonPath);
+      const pass   = deepEqual(actual, expected);
+      results.push({ pass, message: `${jsonPath}: ${JSON.stringify(actual)} ${pass ? '==' : '!='} ${JSON.stringify(expected)}` });
+    }
+  }
+
+  // Response header
+  if (expect.header) {
+    for (const [key, val] of Object.entries(expect.header)) {
+      const actual = response.headers[key.toLowerCase()] || '';
+      const pass   = val instanceof RegExp ? val.test(actual) : actual.includes(String(val));
+      results.push({ pass, message: `header "${key}": "${actual}" ${pass ? 'matches' : 'does not match'} "${val}"` });
+    }
+  }
+
+  // Max latency
+  if (expect.maxLatency !== undefined) {
+    const pass = response.latency <= expect.maxLatency;
+    results.push({ pass, message: `latency ${response.latency}ms ${pass ? '<=' : '>'} ${expect.maxLatency}ms` });
+  }
+
+  return results;
+}
+
+function jsonPartialMatch(actual, expected, path) {
+  if (expected === null || expected === undefined) {
+    return { pass: actual === expected, msg: `${path || 'root'}: ${JSON.stringify(actual)} == ${JSON.stringify(expected)}` };
+  }
+  if (typeof expected !== 'object' || Array.isArray(expected)) {
+    const pass = deepEqual(actual, expected);
+    return { pass, msg: `${path || 'root'}: ${JSON.stringify(actual)} ${pass ? '==' : '!='} ${JSON.stringify(expected)}` };
+  }
+  if (typeof actual !== 'object' || actual === null) {
+    return { pass: false, msg: `${path || 'root'}: expected object, got ${JSON.stringify(actual)}` };
+  }
+  for (const [k, v] of Object.entries(expected)) {
+    const subPath = path ? `${path}.${k}` : k;
+    const result  = jsonPartialMatch(actual[k], v, subPath);
+    if (!result.pass) return result;
+  }
+  return { pass: true, msg: `json structure matches` };
+}
+
+function getJsonPath(obj, jsonPath) {
+  const keys = jsonPath.replace(/^\$\.?/, '').split(/[.\[\]]+/).filter(Boolean);
+  let current = obj;
+  for (const key of keys) {
+    if (current == null) return undefined;
+    current = current[key];
+  }
+  return current;
+}
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== 'object') return false;
+  if (a === null || b === null) return false;
+  const ka = Object.keys(a), kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every(k => deepEqual(a[k], b[k]));
+}
+
+// ─── Variable substitution ────────────────────────────────────────────────────
+function substitute(value, vars) {
+  if (typeof value === 'string') {
+    return value.replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k] ?? `{{${k}}}`);
+  }
+  if (typeof value === 'object' && value !== null) {
+    if (Array.isArray(value)) return value.map(v => substitute(v, vars));
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, substitute(v, vars)]));
+  }
+  return value;
+}
+
+// ─── Test runner ──────────────────────────────────────────────────────────────
+async function runSuite(suite, vars = {}) {
+  const results = [];
+  const allVars = { ...vars };
+
+  for (const test of suite.tests) {
+    if (test.skip) {
+      results.push({ name: test.name, skipped: true });
+      continue;
+    }
+
+    const t = substitute(test, allVars);
+    let response;
+
+    try {
+      response = await fetchRequest({
+        method:  t.method || 'GET',
+        url:     t.url,
+        headers: t.headers || {},
+        body:    t.body,
+        timeout: t.timeout || suite.timeout || 10000,
+      });
+    } catch (e) {
+      results.push({ name: test.name, error: e.message, assertions: [] });
+      continue;
+    }
+
+    const assertions = t.expect ? runAssertions(t.expect, response) : [];
+
+    // Extract variables from response for use in later tests
+    if (t.extract) {
+      for (const [varName, jsonPath] of Object.entries(t.extract)) {
+        const extracted = getJsonPath(response.json, jsonPath);
+        if (extracted !== undefined) allVars[varName] = extracted;
+      }
+    }
+
+    results.push({
+      name:       test.name,
+      status:     response.status,
+      latency:    response.latency,
+      assertions,
+      passed:     assertions.every(a => a.pass),
+      error:      null,
+    });
+  }
+
+  return results;
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+const args       = process.argv.slice(2);
+const flags      = new Set(args.filter(a => a.startsWith('-')));
+const positional = args.filter(a => !a.startsWith('-'));
+
+if (flags.has('--version') || flags.has('-v')) {
+  console.log(`req-test v${VERSION}`); process.exit(0);
+}
+
+if (flags.has('--help') || flags.has('-h')) {
+  console.log(`
+${bold('req-test')} — File-based HTTP test runner
+
+${bold('USAGE')}
+  req-test [file]                  Run tests from a file (default: requests.json)
+  req-test init                    Create a starter requests.json
+
+${bold('OPTIONS')}
+  --verbose    Show all assertions, not just failures
+  --version    Show version
+  --help       Show this help
+
+${bold('TEST FILE FORMAT')}  (requests.json)
+  {
+    "vars": { "base": "http://localhost:3000" },
+    "timeout": 5000,
+    "tests": [
+      {
+        "name": "Get user",
+        "method": "GET",
+        "url": "{{base}}/api/users/1",
+        "expect": {
+          "status": 200,
+          "json": { "id": 1 },
+          "maxLatency": 500
+        },
+        "extract": { "userId": "$.id" }
+      }
+    ]
+  }
+
+${bold('ASSERTIONS')}
+  status         Exact HTTP status code
+  statusRange    Status class: "2xx", "4xx", "5xx"
+  json           Partial JSON match (nested keys)
+  jsonPath       JSONPath assertions: { "$.user.name": "Alice" }
+  bodyContains   String present in response body
+  header         Response header match: { "content-type": "application/json" }
+  maxLatency     Maximum allowed response time in ms
+`);
+  process.exit(0);
+}
+
+// init sub-command
+if (positional[0] === 'init') {
+  const dest = path.join(process.cwd(), CFG_FILE);
+  if (fs.existsSync(dest)) {
+    console.log(yellow(`\n${CFG_FILE} already exists.\n`));
+    process.exit(0);
+  }
+  const starter = {
+    vars: { base: 'https://jsonplaceholder.typicode.com' },
+    timeout: 5000,
+    tests: [
+      {
+        name: 'Get post returns 200',
+        method: 'GET',
+        url: '{{base}}/posts/1',
+        expect: { status: 200, json: { id: 1 }, maxLatency: 2000 },
+      },
+      {
+        name: 'Create post',
+        method: 'POST',
+        url: '{{base}}/posts',
+        headers: { 'Content-Type': 'application/json' },
+        body: { title: 'Test', body: 'Hello', userId: 1 },
+        expect: { status: 201, json: { title: 'Test' } },
+      },
+      {
+        name: 'Non-existent post returns 404',
+        method: 'GET',
+        url: '{{base}}/posts/9999',
+        expect: { status: 404 },
+      },
+    ],
+  };
+  fs.writeFileSync(dest, JSON.stringify(starter, null, 2));
+  console.log(green(`\n✓ Created ${dest}\n`));
+  console.log(dim('  Edit the file then run: req-test\n'));
+  process.exit(0);
+}
+
+const cfgFile = positional[0]
+  ? path.resolve(positional[0])
+  : path.join(process.cwd(), CFG_FILE);
+
+if (!fs.existsSync(cfgFile)) {
+  console.error(red(`\nTest file not found: ${cfgFile}`));
+  console.error(dim(`  Run \`req-test init\` to create a starter ${CFG_FILE}\n`));
+  process.exit(1);
+}
+
+let suite;
+try {
+  suite = JSON.parse(fs.readFileSync(cfgFile, 'utf8'));
+} catch (e) {
+  console.error(red(`\nFailed to parse ${cfgFile}: ${e.message}\n`));
+  process.exit(1);
+}
+
+if (!suite.tests || !suite.tests.length) {
+  console.error(red('\nNo tests found in the suite.\n'));
+  process.exit(1);
+}
+
+const verbose = flags.has('--verbose');
+
+console.log(`\n${bold('req-test')}  ${cyan(path.basename(cfgFile))}`);
+console.log(dim(`  ${suite.tests.length} test(s) · base: ${(suite.vars || {}).base || ''}\n`));
+
+runSuite(suite, suite.vars || {}).then(results => {
+  let passed = 0, failed = 0, skipped = 0, errors = 0;
+
+  for (const r of results) {
+    if (r.skipped) {
+      skipped++;
+      console.log(`  ${dim('○')} ${dim(r.name)}  ${dim('(skipped)')}`);
+      continue;
+    }
+    if (r.error) {
+      errors++;
+      console.log(`  ${red('✘')} ${bold(r.name)}  ${red('ERROR: ' + r.error)}`);
+      continue;
+    }
+    if (r.passed) {
+      passed++;
+      console.log(`  ${green('✓')} ${r.name}  ${dim(r.status + ' · ' + r.latency + 'ms')}`);
+      if (verbose && r.assertions.length) {
+        for (const a of r.assertions)
+          console.log(`    ${green('·')} ${dim(a.message)}`);
+      }
+    } else {
+      failed++;
+      console.log(`  ${red('✘')} ${bold(r.name)}  ${dim(r.status + ' · ' + r.latency + 'ms')}`);
+      for (const a of r.assertions) {
+        if (!a.pass) console.log(`    ${red('✘')} ${a.message}`);
+        else if (verbose) console.log(`    ${green('✓')} ${dim(a.message)}`);
+      }
+    }
+  }
+
+  console.log();
+  const total = passed + failed + errors;
+  const summary = [
+    passed  > 0 ? green(`${passed} passed`)    : null,
+    failed  > 0 ? red(`${failed} failed`)      : null,
+    errors  > 0 ? red(`${errors} error(s)`)    : null,
+    skipped > 0 ? dim(`${skipped} skipped`)    : null,
+  ].filter(Boolean).join('  ');
+
+  console.log(`  ${summary}  ${dim('of ' + (total + skipped) + ' tests')}\n`);
+
+  process.exit(failed > 0 || errors > 0 ? 1 : 0);
+}).catch(e => {
+  console.error(red(`\nUnexpected error: ${e.message}\n`));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@lowdep/req-test",
+  "version": "1.0.0",
+  "description": "File-based HTTP test runner — define tests in JSON, run them like a test suite, zero dependencies",
+  "bin": {
+    "req-test": "bin/req-test.js"
+  },
+  "keywords": [
+    "http",
+    "testing",
+    "api",
+    "rest",
+    "cli",
+    "postman",
+    "newman",
+    "developer-tools",
+    "api testing",
+    "http test runner",
+    "postman alternative",
+    "newman alternative",
+    "rest client",
+    "api assertions",
+    "integration test",
+    "curl test",
+    "zero dependencies",
+    "ci"
+  ],
+  "author": "Rushabh Shah",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "bin/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rushabh5000/req-test.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Rushabh5000/req-test/issues"
+  },
+  "homepage": "https://github.com/Rushabh5000/req-test#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}