RouteKit

v0.12.5 "Powerhouse"

Define · Document · Smoke-test — from a single .routes file

What is RouteKit?

RouteKit is a zero-dependency CLI tool and Node.js library for defining, documenting, and smoke-testing REST API routes from a single human-readable .routes file.

Stop juggling Postman collections, curl scripts, and stale wikis. Write your routes once — RouteKit becomes your contract, your docs, and your integration test suite simultaneously.

# Auth Endpoints
POST /auth/login
  body { "email": "[email protected]", "password": "secret" }
  expect 200
  expect body.token exists
  expect time < 500ms

Quick Start

1 — Install globally

npm install -g routekit-cli

The CLI command is routekit — the package name is routekit-cli because npm is a wild place.

On Windows, RouteKit automatically registers the .routes file type with Windows Explorer (file icon + context-menu actions) as part of the install. No extra steps needed.

2 — Create your first routes file

Create api.routes in your project:

# Health Check
GET /health
  expect 200
  expect body.status = "ok"

# List Users
GET /users
  header Authorization: Bearer {{TOKEN}}
  expect 200
  expect body[] length > 0
  expect time < 300ms

# Create User
POST /users
  header Authorization: Bearer {{TOKEN}}
  body { "name": "Alice", "role": "admin" }
  expect 201
  expect body.id matches ^usr_
  expect header Content-Type = application/json

3 — Run your smoke tests

routekit run --base https://api.example.com --file api.routes

4 — Generate Markdown docs

routekit docs --file api.routes > API_DOCS.md

Installation Details

Global CLI (recommended)

npm install -g routekit-cli

Local project dependency

npm install routekit-cli
npx routekit --help

Verify the install

routekit --help

DSL Reference

The .routes format is plain text — readable by humans, parseable by machines.

File Structure

# Section Name         ← optional grouping headers (start with #)

METHOD /path           ← route declaration (must start at column 0)
  header Name: Value   ← request header (indented)
  body { "json": 1 }   ← request body as JSON (indented)
  expect ASSERTION     ← assertion (indented, multiple allowed)
                       ← blank line ends the route block

HTTP Methods

GET · POST · PUT · PATCH · DELETE · HEAD · OPTIONS

Headers

header Authorization: Bearer {{TOKEN}}
header Content-Type: application/json
header X-Api-Key: {{API_KEY}}

Request Body

Must be valid JSON on a single line:

body { "name": "Alice", "active": true }
body [1, 2, 3]

Assertions (expect)

| Syntax | Type | Example | |---|---|---| | expect 200 | HTTP status code | expect 404 | | expect body.key = value | JSON field equality | expect body.active = true | | expect body.key exists | JSON field presence | expect body.token exists | | expect body.key[] length > N | Array/string length | expect body[] length >= 1 | | expect body.key matches REGEX | Regex pattern | expect body.id matches ^usr_ | | expect header Name = value | Response header | expect header Content-Type = application/json | | expect time < Nms | Max round-trip latency | expect time < 500ms |

Length operators: > < >= <= =

Environment Variables

Use {{VAR_NAME}} in paths, headers, and body values. Load from a .routekit.env file:

# .routekit.env
TOKEN=my-secret-token
BASE_URL=https://api.example.com
API_KEY=abc123

Then run:

routekit run --base {{BASE_URL}} --file api.routes --env .routekit.env

Copy .routekit.env.example to get started:

cp .routekit.env.example .routekit.env

CLI Reference

routekit run

Execute smoke tests against a live server.

routekit run --base <url> [--file <path>] [--env <path>] [--json]

| Flag | Default | Description | |---|---|---| | --base <url> | (required) | Base URL for all requests | | --file <path> | ./api.routes | Path to .routes file | | --env <path> | ./.routekit.env | Environment variables file | | --json | false | Output machine-readable JSON |

Output example:

✔  GET  /health           [123ms]
✔  GET  /users            [201ms]
✖  POST /users            [89ms]
     expected status 201 but got 400

2 passed · 1 failed

Exit code 1 if any test fails — perfect for CI pipelines.

routekit docs

Generate a Markdown route table from your .routes file.

routekit docs [--file <path>]
routekit docs --file api.routes > API_DOCS.md

routekit validate

Parse and validate your .routes file syntax without making any network requests.

routekit validate [--file <path>]

Useful as a pre-commit hook:

{
  "scripts": {
    "precommit": "routekit validate --file api.routes"
  }
}

Programmatic API

RouteKit can be used as a Node.js library:

import { parse, run, generateDocs, loadEnv } from 'routekit-cli';

// 1. Load environment variables
const env = loadEnv('./.routekit.env');

// 2. Parse a .routes source string
const source = `
# Health
GET /health
  expect 200
  expect body.status = "ok"

POST /auth/login
  body { "email": "[email protected]", "password": "s3cr3t" }
  expect 200
  expect body.token exists
`;

const routes = parse(source);

// 3. Run tests against a base URL
const results = await run(routes, 'https://api.example.com', env);

// 4. Inspect results
for (const result of results) {
  const icon = result.passed ? '✔' : '✖';
  console.log(`${icon} ${result.route.method} ${result.route.path} [${result.durationMs}ms]`);
  if (!result.passed) {
    result.errors.forEach(e => console.log(`   → ${e}`));
  }
}

// 5. Generate Markdown docs
const markdown = generateDocs(routes);
console.log(markdown);

Exported API

| Export | Description | |---|---| | parse(source) | Parse a .routes string → Route[] | | run(routes, baseUrl, env?) | Execute routes → Result[] | | generateDocs(routes) | Generate Markdown docs → string | | loadEnv(filePath?) | Load .routekit.env → Record<string,string> | | printResults(results) | Print formatted results to stdout | | ParseError | Error class for syntax errors |

Windows File Association

When installed globally on Windows, RouteKit automatically:

• Registers the .routes file extension
• Sets the RouteKit icon for .routes files in Explorer
• Adds right-click context menu actions:
  • Edit with VS Code
  • Validate with RouteKit
  • Generate Docs (RouteKit)
  • Run Smoke Tests (RouteKit)

To manually trigger the setup (e.g., after a local clone):

npm run setup:windows

Then double-click the generated assets/routekit-local.reg and approve the UAC prompt.

CI / CD Integration

RouteKit exits with code 1 when any test fails, making it ideal for pipelines:

# GitHub Actions
- name: Smoke test staging
  run: npx routekit run --base ${{ secrets.STAGING_URL }} --file api.routes

# npm script
"scripts": {
  "test:integration": "routekit run --base $API_BASE --file api.routes"
}

Examples

See the examples/ directory for ready-to-run .routes files covering common API patterns.

Architecture

routekit/
├── bin/
│   └── routekit.js          # CLI entry point (#!/usr/bin/env node)
├── src/
│   ├── index.js             # Public library exports
│   ├── core/
│   │   ├── parser.js        # .routes DSL parser
│   │   ├── runner.js        # HTTP test executor + assertion engine
│   │   └── env.js           # Environment variable loader/interpolator
│   ├── cli/
│   │   └── docs.js          # Markdown doc generator
│   └── utils/
│       └── reporter.js      # Aesthetic terminal reporter
├── assets/
│   ├── routekit-icon.png    # File type icon
│   └── routekit-filetype.reg  # Windows registry template
└── scripts/
    ├── postinstall.mjs      # Auto-runs on npm install -g
    └── setup-registry.mjs   # Manual Windows setup helper

Contributing

See CONTRIBUTING.md for local development setup and contribution guidelines.

License

MIT © Raft-The-Crab