piss

entries

Replay
NSHipster
Manim
NSHipster
@isolated(any)
NSHipster
Uncertain⟨T⟩
NSHipster
Model Context Protocol (MCP)
NSHipster
Ollama
NSHipster
op run
NSHipster
As We May Code
NSHipster
WWDC 2020
NSHipster
Language Server Protocol
NSHipster

Replay

NSHipster

The year is 2025. You’re writing tests for networking code in your Swift app. You could hit the live API, but then your tests are slow, flaky, and fail whenever that third-party service has a bad day. You could stub <code>URLSession</code>, but then you’re maintaining two implementations of your networking layer. You could maintain JSON fixtures by hand, but there’s no way to capture real responses automatically, so your fixtures go stale without anyone noticing. There’s a better approach: Record real HTTP traffic once, then replay it instantly for every subsequent test run. This pattern has been battle-tested for over fifteen years in other languages. <a href="https://github.com/mattt/Replay">Replay</a> brings it to Swift. <hr /><a id="get-on-with-it"></a> In February 2010, <a href="https://github.com/myronmarston">Myron Marston</a> created <a href="https://github.com/vcr/vcr">VCR</a> for Ruby. Just like a videocassette recorder could capture television for later playback, VCR captured HTTP interactions so tests could replay them without hitting the network. Record once, play back forever. The idea spread. Python got <a href="https://github.com/kevin1024/vcrpy">VCR.py</a> and <a href="https://github.com/kiwicom/pytest-recording">pytest-recording</a>. Java got <a href="https://github.com/betamaxteam/betamax">Betamax</a> (continuing the home video theme). Go got <a href="https://github.com/dnaeon/go-vcr">go-vcr</a>. I’ve used VCR and pytest-recording for years and always missed having something comparable in Swift. <a href="https://github.com/venmo/DVR">DVR</a> from Venmo came closest, using the same <code>URLProtocol</code> injection point that Replay uses. But it was built for a different era of Swift — before we had the tools to make something that felt really nice. <h3> <a class="anchor" href="https://nshipster.com/replay/#for-auld-lang-syne" id="for-auld-lang-syne"></a>For Auld Lang Syne</h3> Being in conversation with that prior art means asking what’s different now. Two things stand out: First, <a href="https://en.wikipedia.org/wiki/HAR_%28file_format%29">HAR</a> became a de facto standard. When Myron built VCR, there was no widely-adopted format for HTTP archives, so he invented one using YAML. That’s where the “cassette” terminology comes from. But around the same time, Jan Odvarko on the Firefox developer tools team was creating HAR (HTTP Archive). Today, every major browser exports HAR. As do Charles Proxy, Proxyman, mitmproxy, and Postman. Replay uses HAR instead of inventing a new format. This means you can capture traffic from Safari’s Network tab and drop it directly into your test fixtures. You can inspect fixtures with any text editor. Second, Swift finally has the extension points we need. Swift Testing traits — especially the <a href="https://developer.apple.com/documentation/testing/testscoping"><code>TestScoping</code> protocol</a> from Swift 6.1 — enable the kind of declarative, per-test configuration that pytest fixtures provide. Package plugins let us build integrated tooling that feels native. These capabilities simply didn’t exist before — not in any way that felt intuitive or convenient. <hr /> <h2> <a class="anchor" href="https://nshipster.com/replay/#how-replay-works" id="how-replay-works"></a>How Replay Works</h2> Add <code>.replay</code> to a test and Replay intercepts HTTP requests, serving responses from a HAR file instead of hitting the network: <pre class="highlight"><code>import Testing import Replay struct User: Codable { let id: Int let name: String let email: String } @Test(.replay("fetchUser")) func fetchUser() async throws { let (data, _) = try await URLSession.shared.data( from: URL(string: "https://api.example.com/users/42")! ) let user = try JSONDecoder().decode(User.self, from: data) #expect(user.id == 42) } </code></pre> The <code>.replay("fetchUser")</code> trait loads responses from <code>Replays/fetchUser.har</code>. Your production code uses <code>URLSession</code> normally. No protocols to define. No mocks to inject. Replay’s interception uses built-in affordances in the <a href="https://developer.apple.com/documentation/foundation/url-loading-system">Foundation URL Loading System</a>, so it works with <code>URLSession.shared</code>, custom sessions, and libraries like <a href="https://nshipster.com/alamofire">Alamofire</a>. <h3> <a class="anchor" href="https://nshipster.com/replay/#the-recording-workflow" id="the-recording-workflow"></a>The Recording Workflow</h3> The first time you run a test with <code>.replay</code>, it fails intentionally: <pre class="highlight"><code>❌ Test fetchUser() recorded an issue at ExampleTests.swift ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚠️ No Matching Entry in Archive ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Request: GET https://api.example.com/users/42 Archive: /path/to/.../Replays/fetchUser.har This request was not found in the replay archive. Options: 1. Run against the live network: REPLAY_PLAYBACK_MODE=live swift test --filter <test-name> 2. Record the archive: REPLAY_RECORD_MODE=once swift test --filter <test-name> </code></pre> This is deliberate. Accidental recording could capture credentials, PII, or session tokens. By requiring you to opt into recording explicitly, Replay ensures you’re always aware when network traffic is being captured. So let’s do that now: <pre class="highlight"><code>REPLAY_RECORD_MODE=once swift test --filter fetchUser </code></pre> This hits the real API, captures the response, and saves it to <code>Replays/fetchUser.har</code>. From then on, the test runs instantly against the recorded fixture. There’s something deeply satisfying about watching a test suite that used to take minutes finish in seconds. <h3> <a class="anchor" href="https://nshipster.com/replay/#whats-in-a-har-file" id="whats-in-a-har-file"></a>What’s in a HAR File</h3> A HAR file is just JSON: <pre class="highlight"><code>{ "log": { "version": "1.2", "creator": { "name": "Replay", "version": "1.0" }, "entries": [ { "request": { "method": "GET", "url": "https://api.example.com/users/42", "headers": [{ "name": "Accept", "value": "application/json" }] }, "response": { "status": 200, "content": { "mimeType": "application/json", "text": "{\"id\":42,\"name\":\"Alice\"}" } } } ] } } </code></pre> Human-readable. Editable. Compatible with a vast ecosystem of tools. 🧑‍🍳💋 <h2> <a class="anchor" href="https://nshipster.com/replay/#handling-sensitive-data" id="handling-sensitive-data"></a>Handling Sensitive Data</h2> HAR files have a way of accumulating secrets. Session cookies, authorization headers, API keys — all captured faithfully alongside the responses you actually care about. Replay addresses this with filters that strip sensitive data during recording: <pre class="highlight"><code>@Test( .replay( "fetchUser", filters: [ .headers(removing: ["Authorization", "Cookie"]), .queryParameters(removing: ["token", "api_key"]) ] ) ) func fetchUser() async throws { /* ... */ } </code></pre> The general principle: configure filters before recording, not after. <aside class="admonition warning"> Always review HAR fixtures before committing. In October 2023, <a href="https://www.nightfall.ai/blog/okta-data-breach-what-happened-impact-and-security-lessons-learned">Okta suffered a breach</a> after attackers obtained HAR files containing session tokens. In response, Cloudflare released a <a href="https://har-sanitizer.pages.dev">HAR sanitizer</a> and Chrome added <a href="https://developer.chrome.com/docs/devtools/network/reference">built-in sanitization</a> to DevTools. </aside> <h2> <a class="anchor" href="https://nshipster.com/replay/#flexible-matching" id="flexible-matching"></a>Flexible Matching</h2> By default, Replay matches requests by HTTP method and full URL. For APIs with volatile query parameters (pagination cursors, timestamps, cache-busters), you can configure looser matching: <pre class="highlight"><code>@Test(.replay("fetchUser", matching: [.method, .path])) func fetchUser() async throws { /* ... */ } </code></pre> Available matchers include <code>.method</code>, <code>.url</code>, <code>.host</code>, <code>.path</code>, <code>.query</code>, <code>.headers([...])</code>, <code>.body</code>, and <code>.custom(...)</code> for arbitrary logic. <h2> <a class="anchor" href="https://nshipster.com/replay/#inline-stubs" id="inline-stubs"></a>Inline Stubs</h2> Replay also supports inline stubs: <pre class="highlight"><code>@Test( .replay( stubs: [ .get("https://api.example.com/health", 200, ["Content-Type": "application/json"], { #"{"status": "ok"}"# }) ] ) ) func testHealthCheck() async throws { let (data, _) = try await URLSession.shared.data( from: URL(string: "https://api.example.com/health")! ) #expect(String(data: data, encoding: .utf8) == #"{"status": "ok"}"#) } </code></pre> This is useful for testing error handling, edge cases, or scenarios where the response content matters less than the status code. <aside class="admonition info"> Martin Fowler’s 2006 article <a href="https://martinfowler.com/articles/mocksArentStubs.html">“Mocks Aren’t Stubs”</a> introduces a taxonomy of test doubles: dummies (passed but never used), fakes (working but simplified implementations), stubs (canned responses), spies (stubs that record calls), and mocks (objects with built-in expectations). According to this ontology, Replay’s fixtures are stubs — they provide predetermined responses without verifying how they’re called. But unlike hand-rolled stubs that drift from reality, these are captured from real API traffic, so they stay honest. </aside> <hr /> Fifteen years of refinement across Ruby, Python, JavaScript, and other ecosystems have established clear best practices for HTTP recording: capture real traffic, strip sensitive data, fail fast when fixtures are missing, provide good error messages when things go wrong. Replay brings all of that to Swift. If you’ve been struggling with flaky API tests, or putting off testing your network code because the overhead felt too high, resolve to give Replay a try. <aside class="parenthetical"> And if you’re reading this on New Year’s Eve, consider it a gift — patterns that have proven themselves, carried forward into a new year. 🥂 </aside> <a href="https://github.com/mattt/Replay">Replay is open source on GitHub.</a> Let me know what you think!