http-assert-cli

Test HTTP endpoints with assertions from the command line — like curl, but with pass/fail testing.

Perfect for health checks, CI pipelines, API smoke tests, and monitoring scripts.

Install

npm install -g http-assert-cli

Or use without installing:

npx http-assert-cli GET https://api.example.com/health --expect-status 200

Usage

http-assert <METHOD> <URL> [OPTIONS]
http-assert --file assertions.json

Examples

Status code assertion

http-assert GET https://api.example.com/health --expect-status 200

POST with body

http-assert POST https://api.example.com/users \
  --body '{"name":"test","email":"[email protected]"}' \
  --expect-status 201

Assert JSON body content

http-assert GET https://api.example.com/users \
  --expect-json '.data.length > 0'

http-assert GET https://api.example.com/status \
  --expect-json '.status == "healthy"'

Assert response header

http-assert GET https://api.example.com/ \
  --expect-header 'content-type: application/json'

Assert body contains string

http-assert GET https://api.example.com/ \
  --expect-body 'healthy'

Multiple assertions at once

http-assert GET https://api.example.com/health \
  --expect-status 200 \
  --expect-body 'ok' \
  --expect-header 'content-type: application/json'

Custom request headers

http-assert GET https://api.example.com/private \
  --header 'Authorization: Bearer mytoken' \
  --expect-status 200

Run from assertions file

http-assert --file assertions.json

Assertions File Format

[
  {
    "method": "GET",
    "url": "https://api.example.com/health",
    "expect": {
      "status": 200,
      "body": "ok"
    }
  },
  {
    "method": "POST",
    "url": "https://api.example.com/users",
    "body": { "name": "test" },
    "expect": {
      "status": 201
    }
  },
  {
    "method": "GET",
    "url": "https://api.example.com/users",
    "headers": { "Authorization": "Bearer mytoken" },
    "expect": {
      "status": 200,
      "json": ".data.length > 0",
      "header": "content-type: application/json"
    }
  }
]

CI Integration

GitHub Actions

name: API Health Check

on:
  push:
    branches: [main]
  schedule:
    - cron: '*/15 * * * *'  # every 15 minutes

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - name: Install http-assert-cli
        run: npm install -g http-assert-cli

      - name: Check API health
        run: http-assert GET https://myapp.com/health --expect-status 200 --expect-body ok

      - name: Run full assertion suite
        run: http-assert --file assertions.json

GitLab CI

smoke-tests:
  image: node:18
  script:
    - npm install -g http-assert-cli
    - http-assert GET $API_URL/health --expect-status 200
    - http-assert --file assertions.json

Shell script / cron monitoring

#!/bin/bash
if ! http-assert GET https://myapp.com/health --expect-status 200 --silent; then
  echo "ALERT: Health check failed!" | mail -s "Downtime Alert" [email protected]
fi

Options

| Flag | Description | |------|-------------| | --expect-status <code> | Assert HTTP status code | | --expect-body <string> | Assert response body contains string | | --expect-json <expr> | Assert JSON body with JS expression | | --expect-header <name: val> | Assert response header | | --body <json> | Request body (JSON string) | | --header <name: val> | Add request header (repeatable) | | --timeout <ms> | Timeout in ms (default: 10000) | | --file <path> | Run assertions from JSON file | | --silent | Suppress output, use exit codes only | | --verbose | Show response body on failure |

Exit Codes

| Code | Meaning | |------|---------| | 0 | All assertions passed | | 1 | One or more assertions failed | | 2 | Usage/configuration error |

Zero Dependencies

http-assert-cli uses only Node.js built-in modules (https, http, fs, url). No node_modules, no supply chain risk.

License

MIT © Wilson Xu