apophis-fastify/docs/cache-and-ci.md

# Cache & CI/CD Integration

APOPHIS includes an incremental test cache that speeds up test runs by skipping unchanged routes. This document covers cache invalidation strategies and CI/CD integration.

## How the Cache Works

The cache stores generated test commands per route in `.apophis-cache.json`:

```json
{
  "version": 1,
  "entries": {
    "a1b2c3d4": {
      "routeHash": "a1b2c3d4",
      "schemaHash": "e5f6g7h8",
      "path": "/users",
      "method": "GET",
      "commands": [{ "params": {}, "headers": {} }],
      "timestamp": 1704067200000
    }
  }
}
```

Each entry is keyed by a hash of the route's path, method, and schema. If the schema changes, the entry is automatically invalidated.

## Environment Behavior

| Environment | Cache | Reason |
|-------------|-------|--------|
| `production` | Enabled by default | Set `APOPHIS_DISABLE_CACHE=1` to opt-out |
| `test` | Enabled by default | Set `APOPHIS_DISABLE_CACHE=1` to opt-out |
| `development` | Enabled by default | Speeds up iterative testing |
| default | Enabled by default | Backward compatible |

## Cache Invalidation

### 1. Automatic Invalidation

The cache is automatically invalidated when:
- A route's schema changes (detected via schema hash mismatch)
- The cache file is corrupted or has the wrong version

### 2. CI/CD Hints via Environment Variable

Set `APOPHIS_CHANGED_ROUTES` to invalidate specific routes on the next test run. The cache is checked during `contract()` and `stateful()` test runs:

```bash
# Exact path
APOPHIS_CHANGED_ROUTES=/users

# Multiple paths (comma-separated)
APOPHIS_CHANGED_ROUTES=/users,/items,/orders

# Method prefix
APOPHIS_CHANGED_ROUTES=GET /users,POST /orders

# Wildcards
APOPHIS_CHANGED_ROUTES=/api/*,/admin/**
```

Patterns support:
- **Exact path**: `/users`
- **Method prefix**: `GET /users`
- **Single wildcard**: `/api/*` (matches one segment)
- **Double wildcard**: `/api/**` (matches any depth)

### 3. CI/CD Hints via File

Create `.apophis-hints.json` in your project root:

```json
{
  "changed": [
    "/users",
    "GET /items",
    "/api/**"
  ]
}
```

This is useful when your CI system can write a file but setting env vars is awkward.

## CI/CD Examples

### GitHub Actions

See `docs/examples/github-actions.yml` for a complete workflow.

Key steps:
1. Run tests with cache
2. If tests fail, re-run without cache to rule out cache issues
3. On main branch, clear cache after deployment

### GitLab CI

See `docs/examples/gitlab-ci.yml` for a complete pipeline.

### Best Practices

1. **Commit the cache file?** No — `.apophis-cache.json` should be in `.gitignore`
2. **Cache in CI?** Yes — cache `.apophis-cache.json` between runs for faster builds
3. **Invalidate on deploy?** Yes — set `APOPHIS_CHANGED_ROUTES` from your deployment diff
4. **Debug cache issues?** Set `APOPHIS_LOG_LEVEL=debug` to see cache hits/misses

## Logging

Cache operations are logged at the `info` level:

```
[apophis] Invalidated 3 cached route(s) from CI/CD hints
```

Set `APOPHIS_LOG_LEVEL=debug` to see detailed cache operations.