API smoke test runner with JSON test files and JUnit XML

What it does

Quickly checks that an API works, after a deploy or during local development.

• Write method, URL, headers, body, expected status and max latency per test in a JSON file
• JSON path assertions (for example $.items[0].id): exists or absent, equals, type, length, contains, regex, numeric comparisons
• Response header and body text checks
• Environment variables such as ${API_TOKEN}, also loadable from a .env-style file. Substituted values are replaced with *** in the console, JSON and JUnit XML output
• Pass/fail table on screen, plus JUnit XML for CI and a JSON report
• POST, PUT, PATCH and DELETE are sent only with --allow-write (skipped by default)
• Redirects are not followed by default, so a 301 can be asserted as-is

How to use

python scripts/smoke.py smoke-tests.json --env-file .env.smoke --junit smoke-junit.xml

Ask the agent to write and run smoke tests for your API. It writes the test file, runs it and explains likely causes of failures. Works with Claude, Codex, Hermes Agent and Cursor.

Requirements

• Python 3 (standard library only)

Caveats

• Requests go only to the URLs in the test file. Use --allow-write only for environments that may be written to.
• Latency is a single client-side measurement, not a load test.
• Values shorter than 3 characters are not masked. Do not write secrets into the test file.
• JSON paths do not support wildcards or filters.