VCR-style record/replay for HTTP when using Req, integrating with Req.Test.

Reqord allows you to record HTTP interactions to cassette files and replay them in your tests without requiring any application code changes.

Installation

Add reqord to your list of dependencies in mix.exs:

def deps do
  [
    {:req, "~> 0.5"},
    {:reqord, "~> 0.1.0"}
  ]
end

Quick Start

1. Configure Req to use Req.Test in your test environment

In config/test.exs:

config :my_app,
  req_options: [plug: {Req.Test, MyApp.ReqStub}]

2. Use Reqord.Case in your tests

defmodule MyApp.APITest do
  use Reqord.Case

  # Specify your Req.Test stub name
  defp default_stub_name, do: MyApp.ReqStub

  test "fetches user data" do
    client = Req.new(Application.get_env(:my_app, :req_options, []))
    {:ok, response} = Req.get(client, url: "https://api.example.com/users/123")

    assert response.status == 200
    assert response.body["name"] == "John Doe"
  end
end

3. Record cassettes on first run

# Record mode - hits live API and saves responses
REQORD=record API_TOKEN=xxx mix test

# Subsequent runs use replay mode (default) - no network calls
mix test

Modes

Control the VCR mode via the REQORD environment variable:

• :replay (default) - Only replay from cassettes, raise on misses
• :record - Always forward to live network and record
• :auto - Replay if match found, otherwise record via live proxy

Examples

Basic Usage with Reqord.Case

defmodule MyApp.WeatherAPITest do
  use Reqord.Case

  defp default_stub_name, do: MyApp.ReqStub

  # Creates cassette: test/support/cassettes/WeatherAPI/fetches_forecast.jsonl
  test "fetches forecast" do
    client = Req.new(plug: {Req.Test, MyApp.ReqStub})
    {:ok, response} = Req.get(client, url: "https://api.weather.com/forecast")

    assert response.status == 200
    assert is_list(response.body["forecast"])
  end

  # Custom cassette name
  @tag vcr: "weather/special_forecast"
  test "with custom cassette" do
    client = Req.new(plug: {Req.Test, MyApp.ReqStub})
    {:ok, response} = Req.get(client, url: "https://api.weather.com/special")

    assert response.status == 200
  end
end

Manual Installation

For more control, you can install Reqord manually:

defmodule MyApp.CustomTest do
  use ExUnit.Case

  setup do
    Req.Test.set_req_test_to_private()
    Req.Test.set_req_test_from_context(%{async: true})

    Reqord.install!(
      name: MyApp.ReqStub,
      cassette: "my_custom_cassette",
      mode: :replay
    )

    :ok
  end

  test "custom setup" do
    client = Req.new(plug: {Req.Test, MyApp.ReqStub})
    {:ok, response} = Req.get(client, url: "https://api.example.com/data")
    assert response.status == 200
  end
end

Working with Spawned Processes

If your test spawns processes that make HTTP requests:

test "with spawned task" do
  client = Req.new(plug: {Req.Test, MyApp.ReqStub})

  task = Task.async(fn ->
    Req.get(client, url: "https://api.example.com/data")
  end)

  # Allow the task's process to use the stub
  Reqord.allow(MyApp.ReqStub, self(), task.pid)

  {:ok, response} = Task.await(task)
  assert response.status == 200
end

POST/PUT/PATCH Requests

Reqord distinguishes requests with different bodies:

test "creates users" do
  client = Req.new(plug: {Req.Test, MyApp.ReqStub})

  # These will create separate cassette entries
  {:ok, resp1} = Req.post(client,
    url: "https://api.example.com/users",
    json: %{name: "Alice"}
  )

  {:ok, resp2} = Req.post(client,
    url: "https://api.example.com/users",
    json: %{name: "Bob"}
  )

  assert resp1.body["name"] == "Alice"
  assert resp2.body["name"] == "Bob"
end

How It Works

Request Matching

Reqord matches requests using a deterministic key:

METHOD NORMALIZED_URL BODY_HASH

• Method: HTTP method (GET, POST, etc.)
• Normalized URL: Query parameters sorted, auth params removed
• Body Hash: SHA-256 hash for POST/PUT/PATCH, - for others

Automatic Redaction

Sensitive data is automatically redacted:

Headers (set to <REDACTED>):

• authorization

Query parameters (set to <REDACTED>):

• token, apikey, api_key

Volatile response headers (removed):

• date, server, set-cookie, request-id, x-request-id, x-amzn-trace-id

Cassette Format

Cassettes are stored as JSONL files in test/support/cassettes/:

{"key":"GET https://api.example.com/users -","req":{...},"resp":{...}}
{"key":"POST https://api.example.com/users abc123...","req":{...},"resp":{...}}

Workflow

# 1. Write tests using Reqord.Case
# 2. Record cassettes (hits live API)
REQORD=record API_TOKEN=xxx mix test

# 3. Commit cassettes to git
git add test/support/cassettes/
git commit -m "Add API cassettes"

# 4. Run tests in replay mode (no network calls)
mix test

# 5. Update cassettes when API changes
REQORD=record API_TOKEN=xxx mix test

Integration with Req.Test

Reqord works alongside your existing Req.Test stubs:

test "with mixed stubs" do
  # Add a high-priority stub for specific URL
  Req.Test.stub(MyApp.ReqStub, fn
    %{request_path: "/special"} = conn ->
      Req.Test.json(conn, %{special: true})
  end)

  client = Req.new(plug: {Req.Test, MyApp.ReqStub})

  # This hits your stub
  {:ok, resp1} = Req.get(client, url: "https://api.example.com/special")
  assert resp1.body["special"] == true

  # This falls through to VCR
  {:ok, resp2} = Req.get(client, url: "https://api.example.com/other")
end