Documentation
¶
Overview ¶
Package mock provides a record/replay HTTP RoundTripper layer for tests that exercise the engine's HTTP-fetch paths without paying real-network latency or flakiness costs.
Lifecycle
Replay (default, hermetic): reads testdata/mocks/<slug>.json and serves the canned response on every RoundTrip. Test fails fast when the slug file is missing — recordings are explicit, deterministic artifacts that should be committed alongside the test.
Record (opt-in): activated only when SEAPORTAL_RECORD_MOCKS=1 is set. Wraps the real transport, ferries the response back to the caller, and persists status/headers/body/latency to testdata/mocks/<slug>.json. When the env var is unset, Record degrades to Replay so tests stay hermetic by default.
CI safety: recording is refused when CI=true to prevent accidental overwrites from automated pipelines. Recordings should be produced and reviewed locally.
On-disk format (testdata/mocks/<slug>.json):
{
"url": "https://example.com/foo",
"method": "GET",
"captured_at": "2026-05-17T12:34:56Z",
"latency_ms": 142,
"response": {
"status_code": 200,
"headers": {"Content-Type": ["text/html; charset=utf-8"]},
"body_base64": "PGh0bWw+..."
}
}
Body is base64-encoded so binary responses (gzip/br/zstd/PDF) round-trip cleanly without JSON-escaping pitfalls.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var MocksDir = filepath.Join("testdata", "mocks")
MocksDir is the on-disk directory relative to the test's working directory where recordings live. Tests typically run with cwd == package dir, so this resolves to <pkg>/testdata/mocks. Exposed so callers (or tests of the mock package itself) can override for temp-dir round-trips.
Functions ¶
func Record ¶
func Record(t *testing.T, slug string) http.RoundTripper
Record returns a RoundTripper that wraps the live transport and persists each response to testdata/mocks/<slug>.json. When SEAPORTAL_RECORD_MOCKS=1 is unset, Record degrades to Replay so the default test run stays hermetic. When CI=true is set alongside the record flag, Record fails fast — CI runners should never rewrite fixtures.
The base RoundTripper used for the live request is http.DefaultTransport; callers needing the utls Chrome fingerprint should configure that at the caller side (or use Record only against test httptest.Server upstreams).
func Replay ¶
func Replay(t *testing.T, slug string) http.RoundTripper
Replay returns an http.RoundTripper that serves the recording stored at testdata/mocks/<slug>.json. The incoming request URL is ignored — one slug maps to one canned response. Calls t.Fatalf when the slug file is missing or malformed; this is the desired behaviour so missing fixtures surface loudly rather than silently passing.
Types ¶
type RecordedResponse ¶
type RecordedResponse struct {
StatusCode int `json:"status_code"`
Headers http.Header `json:"headers"`
BodyBase64 string `json:"body_base64"`
}
RecordedResponse mirrors the response fields needed to faithfully replay an HTTP response: status, headers, and the raw (still-encoded) body bytes.
type Recording ¶
type Recording struct {
URL string `json:"url"`
Method string `json:"method"`
CapturedAt time.Time `json:"captured_at"`
LatencyMs int64 `json:"latency_ms"`
Response RecordedResponse `json:"response"`
}
Recording is the on-disk format. Exported so callers writing custom fixtures can construct one directly without going through Record.
Source Files