Files

T

John Dvorak 6c39bd0a6c docs: final cleanup and accuracy pass before public push

- Fix const inference bug: wrap inferred contracts with status-code guards
- Add integration test for status-guarded contract inference
- Tighten and deduplicate docs across verify, qualify, getting-started, cli
- Fix broken cross-references and TypeScript→JavaScript conversions
- Fix factual errors: license, Date.now(), sampling defaults, cache env
- Add missing features: --workspace, --generation-profile, json-summary formats
- Move stale extension docs (AUTH-RATE-LIMIT-REVISED, HTTP-EXTENSIONS) to attic
- Update PLUGIN_CONTRACTS_SPEC status to Implemented
- Build: clean | Tests: 849 pass, 0 fail

2026-04-30 11:25:30 -07:00

3.0 KiB

Raw Blame History

Getting Started with APOPHIS

Get from install to your first behavioral bug in 10 minutes.

Prerequisites

Node.js 20.x or 22.x
A Fastify app with @fastify/swagger registered

Step 1: Install

npm install apophis-fastify fastify @fastify/swagger

Step 2: Scaffold

apophis init --preset safe-ci

This creates:

apophis.config.js — config with a quick profile
APOPHIS.md — preset-specific guidance
Package script: npm run apophis:verify

Step 3: Add One Behavioral Contract

Pick one important route. Add an x-ensures clause that checks behavior across operations:

import crypto from 'crypto';

app.post('/users', {
  schema: {
    'x-category': 'constructor',
    'x-ensures': [
      // BEHAVIORAL: Creating a user must make it retrievable
      'response_code(GET /users/{response_body(this).id}) == 200'
    ]
  }
}, async (request, reply) => {
  const { name } = request.body;
  const id = `usr-${crypto.createHash('sha256').update(name).digest('hex').slice(0, 8)}`;
  reply.status(201);
  return { id, name };
});

Warning: Using Date.now() or Math.random() in handlers breaks determinism and replay. Use a stable function of the input instead.

Step 4: Run Verify

apophis verify --profile quick --routes "POST /users"

Example Failure

If your GET /users/:id handler has a bug (always returns 404), APOPHIS catches it:

Contract violation
POST /users
Profile: quick
Seed: 42

Expected
  response_code(GET /users/{response_body(this).id}) == 200

Observed
  GET /users/usr-123 returned 404

Why this matters
  The resource created by POST /users is not retrievable.

Replay
  apophis replay --artifact reports/apophis/failure-2026-04-28T12-30-22Z.json

Next
  Check the create/read consistency for POST /users and GET /users/{id}.

Step 5: Replay and Fix

Copy the replay command and run it:

apophis replay --artifact reports/apophis/failure-2026-04-28T12-30-22Z.json

Fix the bug in your handler. Re-run verify. The failure should now pass.

Next Steps

Add more routes to your profile: apophis verify --profile quick --routes "POST /users,PUT /users/:id"
Use wildcards to match route patterns: apophis verify --routes 'POST /api/*'
Run all routes: apophis verify --profile quick
Run only changed routes in CI: apophis verify --profile ci --changed
- Requires a git repository.
Use machine-readable output in CI: apophis verify --profile ci --format json-summary
Add observe mode for runtime drift detection: see observe.md
Add qualify mode for scenario, stateful, and chaos checks: see qualify.md

Config Reference

For the full configuration reference, see CLI Reference.

Monorepo Workspaces

Use --workspace to run verify or doctor across all packages:

apophis verify --workspace --profile quick --format json

See CLI Reference for workspace output format and exit codes.

3.0 KiB Raw Blame History