GitHub - ojuschugh1/etch: Zero-config API change detection. Record, diff, and approve real API responses - no tests required.

etch record          # capture baseline
etch test            # detect changes
etch test --spec api.yaml  # detect + validate against contract
etch approve         # accept intentional changes

Test Summary (mode: smart):
  Total:      3
  Matches:    1
  Mismatches: 2
  Breakdown:  1 critical, 1 warning

  ✗ GET http://api.example.com/users
    ✗ status_code: 200 → 500  [HTTP status code changed]
    ! body.users[0].role: "admin" → "viewer"  [value changed]
    ~ headers.Date: <http-date> → <http-date>  [dynamic field (likely noise)]

Schema Validation:
  ✗ body.email: field missing from response
  ! body.metadata: field not defined in spec (undocumented)
  Schema: 1 error(s), 1 warning(s)

✗ Unsafe changes detected
  2 mismatch(es)
  1 schema violation(s)

# one-liner (requires Go 1.22+)
go install github.com/ojuschugh1/etch/cmd/etch@latest

git clone https://github.com/ojuschugh1/etch.git
cd etch
make build

# 1. record - capture API responses as baseline
etch record --port 8080
# (in another terminal) run your app with http_proxy=http://localhost:8080
# ctrl+c when done

# 2. auto-suppress noisy fields (timestamps, IDs, trace headers)
etch noise --write

# 3. test - detect what changed
etch test --port 8080
# (run the same requests again)
# ctrl+c - see summary

# 4. validate - check against your API spec (optional)
etch test --spec openapi.yaml

# 5. approve - accept intentional changes
etch approve

┌─────────────┐     ┌───────────┐     ┌──────────────┐
│  Your App   │────▶│   Etch    │────▶│  Upstream    │
│             │◀────│  (proxy)  │◀────│  API Server  │
└─────────────┘     └───────────┘     └──────────────┘
                         │
                    ┌────┴────┐
                    │  .snap  │
                    │  files  │
                    └─────────┘

# 1. record a baseline during development
http_proxy=http://localhost:8080 etch record
# run your app's payment flow, user flow, etc through the proxy
# ctrl+c when done

# 2. auto-ignore noisy fields (timestamps, request IDs, trace headers)
etch noise --write

# 3. in CI, test against baseline using schema mode
#    (only flags type/structure changes, ignores value changes)
etch test --mode schema --ci
# exit 0 = types and structure unchanged, safe to deploy
# exit 1 = something structural changed, investigate before deploying

# 4. when something changes, see what happened
etch diff
etch history --endpoint "GET /users"

# 5. if the change is intentional, approve it
etch approve

etch record                    # capture baseline snapshots
etch test                      # detect changes (exit code 1 if mismatches)
etch test --spec api.yaml      # detect changes + validate against spec
etch diff                      # show pending changes
etch approve                   # accept all pending changes
etch approve --request <hash>  # accept one specific change
etch approve --pattern <field> # accept all changes matching a field name
etch approve --dry-run         # preview what would be approved

etch validate --spec api.yaml  # validate snapshots against OpenAPI spec
etch verify                    # run metamorphic relation checks
etch coverage                  # show which endpoints have snapshots
etch learn                     # show learned field constraints
etch noise                     # detect noisy fields, suggest .etchignore rules
etch noise --write             # auto-generate .etchignore

etch openapi                   # generate OpenAPI spec from snapshots
etch mock                      # serve snapshots as a mock server
etch report                    # generate HTML diff report
etch watch                     # continuously monitor for changes
etch ca-cert                   # print CA cert path (for HTTPS)
etch version                   # print version

--port       Proxy listen port (default: 8080)
--snap-dir   Snapshot directory (default: .etch/snapshots)
--config     Config file path (default: .etch/config.json)
--ci         CI mode: no color, non-interactive
--mode       Comparison mode: raw, smart (default), strict
--explain    Show why fields were normalized or ignored
--spec       OpenAPI spec for schema validation (on test command)

etch test --mode raw      # catch everything, including noise
etch test --mode smart    # daily usage (default)
etch test --mode strict   # conservative normalization

# .etchignore
headers.Date
headers.X-Request-Id
body.created_at
body.meta.*

etch noise          # see what's noisy and why (with confidence %)
etch noise --write  # auto-generate .etchignore

etch validate --spec openapi.yaml

etch test --spec openapi.yaml

{
  "relations": [
    {
      "name": "user count matches list",
      "type": "consistency",
      "endpoints": ["GET /users", "GET /users/count"],
      "field": "users",
      "count_field": "count"
    },
    {
      "name": "admin users are subset of all users",
      "type": "subset",
      "endpoints": ["GET /users?role=admin", "GET /users"],
      "field": "users"
    }
  ]
}

etch verify
# Relation checks: 2 passed, 0 failed
#   ✓ user count matches list - array length matches count (2)
#   ✓ admin users are subset - filtered results are a subset of unfiltered

{
  "llm": {
    "endpoint": "https://api.openai.com/v1/chat/completions",
    "api_key": "sk-...",
    "model": "gpt-4o-mini"
  }
}

etch ca-cert  # print CA cert path
# trust it, then:
https_proxy=http://localhost:8080 curl https://api.example.com/users

{
  "port": 8080,
  "snap_dir": ".etch/snapshots",
  "excluded_headers": ["Date", "Authorization", "X-Request-Id"],
  "normalizers": [
    {"pattern": "ORD-[0-9]{6}", "replace": "<order-id>"}
  ],
  "env": {
    "BASE_URL": "https://api.staging.example.com"
  },
  "hooks": {
    "before_test": "make db-reset",
    "after_record": "git add .etch/"
  }
}

etch test --ci --inject-header "Authorization: Bearer $FRESH_TOKEN"

etch test --ci --spec openapi.yaml
# exit 0 = clean, exit 1 = changes detected or schema violations

etch/
├── cmd/etch/            # CLI entry point
├── internal/
│   ├── approval/        # approve/reject workflow
│   ├── ca/              # TLS certificate generation
│   ├── config/          # config + CLI flag merging
│   ├── constraint/      # field constraint learning
│   ├── coverage/        # endpoint coverage reports
│   ├── diff/            # comparison engine + severity
│   ├── hash/            # deterministic request hashing
│   ├── ignore/          # .etchignore parser
│   ├── llm/             # optional LLM diff summaries
│   ├── mock/            # mock server from snapshots
│   ├── noise/           # noise detection + normalization
│   ├── openapi/         # OpenAPI spec generation
│   ├── proxy/           # HTTP/HTTPS reverse proxy
│   ├── schema/          # OpenAPI schema validation
│   └── snapshot/        # snapshot file I/O
├── examples/            # language-specific examples
├── .github/             # CI templates
├── .gitlab/             # CI templates
└── Makefile

make test                # all tests
go test ./... -v         # verbose
go test -race ./...      # race detector