Skip to documentation

Guide · Record and replay

Preview

Last verified

Capture real provider answers, then test without them

When no fixture matches, DotMock can forward the request to the real provider, record the response, and return it. Later runs replay the recording without network access, and any recording can be promoted into an editable fixture.

VCR record, replay, and recording promotion are in preview. Hosted API settings and local dotmock.yaml files accept the fallback types proxy, record, replay, and none.

In this guide

  • Configure provider upstreams
  • Record, replay, and off modes
  • Promote recordings into fixtures
  • Credential and network safety

Prerequisites

  • An LLM DotMock workspace, or a local dotmock.yaml served by dotmock serve
  • The workspace ID in $API_ID and its runtime URL in $MOCK_URL (SDK base URL $MOCK_URL/v1 for OpenAI-compatible clients)
On this page
  1. Configure upstreams
  2. Record, replay, and off
  3. Promote recordings into fixtures
  4. Credentials, redaction, and network safety

Configure upstreams

vcrUpstreams maps a provider name (openai, anthropic, gemini, bedrock, azure, ollama, cohere) or default to the provider's base URL. The incoming path is appended, so use the host root: https://api.openai.com, not …/v1. fallback.upstream, when set, overrides the map for every provider.

API settings
{
  "vcrUpstreams": {
    "openai": "https://api.openai.com",
    "anthropic": "https://api.anthropic.com"
  },
  "fallback": { "type": "proxy" }
}

CLI
dotmock llm vcr $API_ID \
  --upstream openai=https://api.openai.com \
  --upstream anthropic=https://api.anthropic.com \
  --mode record

Record, replay, and off

The mode is fallback.type, which only applies to requests that match no fixture. Fixtures always win, so you can mock the scenarios you care about and let everything else pass through.

  • proxy (CLI --mode record) — forward to the upstream, record the response, and return it; responses carry x-dotmock-vcr: proxy; an unreachable or rejected upstream returns 502 upstream_error
  • replay (CLI --mode replay) — return a stored recording whose key matches, without network access; responses carry x-dotmock-vcr: replay; a miss returns 404 no_fixture_matched
  • none (CLI --mode off) — no fallback; unmatched requests return 404
  • record — local dotmock.yaml alias of proxy
  • Without fallback.type, settings.mode of proxy, hybrid, or record selects proxy and replay selects replay

Promote recordings into fixtures

Recordings are kept per API (up to 200, for 7 days, bodies up to 1 MB), each with a suggested fixture. Promotion copies that suggestion into the fixture list so you can tighten the match, template the content, and commit it. Promoted fixtures can be created disabled for review.

List and promote
dotmock llm recordings $API_ID --limit 20
dotmock llm promote $API_ID 0 --name "refund answer" --priority 30 --disabled

Expected result: A new fixture named "refund answer" appears at priority 30, disabled, with the recorded match and response ready for review.

Credentials, redaction, and network safety

To record, the client sends its real provider key as usual. DotMock forwards credentials to the configured upstream only, strips x-dotmock-* and hop-by-hop headers, and redacts Authorization, x-api-key, api-key, x-goog-api-key, cookie, and x-amz-security-token in recordings and the journal. Nothing secret is stored in a promoted fixture.

Upstreams must be https URLs. Hostnames such as localhost, backend, redis, postgres, dotmock-server, mcp, metadata, and *.internal, *.local, or *.localhost are rejected when settings are saved. At dial time DotMock resolves the host, refuses private, loopback, link-local, CGNAT, multicast, and reserved addresses, connects to the vetted IP, and does not follow redirects.