Test mocking utilities for PinStripe, wrapping Req.Test with sensible defaults.

This module provides a thin wrapper around Req.Test with two main benefits:

1. Single Namespace: All PinStripe testing utilities under PinStripe.Test.*
2. Sensible Defaults: Functions default to using PinStripe as the stub name

Relationship to Req.Test

This module delegates core functionality to Req.Test. For advanced use cases or detailed documentation, refer to the Req.Test documentation.

The main functions are:

• stub/1 and stub/2 - Create request stubs
• expect/1, expect/2, and expect/3 - Create request expectations
• allow/2 and allow/3 - Allow other processes to use stubs/mocks
• json/2 - Create JSON responses (Stripe API returns JSON)
• transport_error/2 - Simulate network errors

High-Level Stripe Helpers

For common Stripe operations, use these helpers that automatically handle URL resolution:

• stub_read/2 - Stub read/list operations
• stub_create/2 - Stub create operations
• stub_update/2 - Stub update operations
• stub_delete/2 - Stub delete operations
• stub_error/3 - Stub error responses

Setup

Configure your test environment to use Req.Test:

# config/test.exs
config :pin_stripe,
  stripe_api_key: "sk_test_...",
  req_options: [plug: {Req.Test, PinStripe}]

High-Level Helpers (Recommended)

The easiest way to stub PinStripe operations is to use the high-level helper functions that mirror PinStripe.Client operations. These automatically handle URL resolution and HTTP method matching:

test "reads a customer using stub_read" do
  Mock.stub_read("cus_123", %{"id" => "cus_123", "email" => "test@example.com"})

  {:ok, response} = Client.read("cus_123")
  assert response.body["email"] == "test@example.com"
end

test "creates a customer using stub_create" do
  Mock.stub_create(:customers, %{"id" => "cus_new", "email" => "new@example.com"})

  {:ok, response} = Client.create(:customers, %{email: "new@example.com"})
  assert response.body["id"] == "cus_new"
end

test "updates a customer using stub_update" do
  Mock.stub_update("cus_123", %{"id" => "cus_123", "name" => "Updated Name"})

  {:ok, response} = Client.update("cus_123", %{name: "Updated Name"})
  assert response.body["name"] == "Updated Name"
end

test "deletes a customer using stub_delete" do
  Mock.stub_delete("cus_123", %{"id" => "cus_123", "deleted" => true})

  {:ok, response} = Client.delete("cus_123")
  assert response.body["deleted"] == true
end

test "stubs errors using stub_error" do
  Mock.stub_error("cus_nonexistent", 404, %{
    "error" => %{"code" => "resource_missing"}
  })

  {:error, response} = Client.read("cus_nonexistent")
  assert response.status == 404
end

These helpers work seamlessly with fixtures:

test "uses fixtures with helpers" do
  customer = Fixtures.load(:customer)
  Mock.stub_read("cus_123", customer)

  error = Fixtures.load(:error_404)
  Mock.stub_error("cus_missing", 404, error)
end

Basic Usage with Raw Data (Lower-Level)

The simplest approach is to stub responses with inline data:

test "reads a customer" do
  Mock.stub(fn conn ->
    if conn.method == "GET" and conn.request_path == "/v1/customers/cus_123" do
      Mock.json(conn, %{"id" => "cus_123", "email" => "test@example.com"})
    else
      conn
    end
  end)

  {:ok, response} = Client.read("cus_123")
  assert response.body["email"] == "test@example.com"
end

test "creates a customer" do
  Mock.stub(fn conn ->
    if conn.method == "POST" and conn.request_path == "/v1/customers" do
      Mock.json(conn, %{"id" => "cus_new", "email" => "new@example.com"})
    else
      conn
    end
  end)

  {:ok, response} = Client.create(:customers, %{email: "new@example.com"})
  assert response.body["id"] == "cus_new"
end

test "lists customers" do
  Mock.stub(fn conn ->
    if conn.method == "GET" and conn.request_path == "/v1/customers" do
      Mock.json(conn, %{
        "object" => "list",
        "data" => [
          %{"id" => "cus_1", "email" => "user1@example.com"},
          %{"id" => "cus_2", "email" => "user2@example.com"}
        ],
        "has_more" => false
      })
    else
      conn
    end
  end)

  {:ok, response} = Client.read(:customers)
  assert length(response.body["data"]) == 2
end

Using Fixtures

For more realistic test data, use PinStripe.Test.Fixtures to load fixture files:

test "reads a customer using fixture" do
  Mock.stub(fn conn ->
    if conn.method == "GET" and conn.request_path == "/v1/customers/cus_123" do
      customer = Fixtures.load(:customer)
      Mock.json(conn, customer)
    else
      conn
    end
  end)

  {:ok, response} = Client.read("cus_123")
  assert response.body["object"] == "customer"
end

test "reads a customer with custom fixture data" do
  Mock.stub(fn conn ->
    if conn.method == "GET" and conn.request_path == "/v1/customers/cus_123" do
      customer = Fixtures.load(:customer, email: "custom@example.com", name: "Custom Name")
      Mock.json(conn, customer)
    else
      conn
    end
  end)

  {:ok, response} = Client.read("cus_123")
  assert response.body["email"] == "custom@example.com"
  assert response.body["name"] == "Custom Name"
end

Stubbing Errors

Use Plug.Conn.put_status/2 to return error responses:

test "handles 404 error" do
  Mock.stub(fn conn ->
    if conn.method == "GET" and conn.request_path == "/v1/customers/cus_nonexistent" do
      conn
      |> Plug.Conn.put_status(404)
      |> Mock.json(%{
        "error" => %{
          "type" => "invalid_request_error",
          "code" => "resource_missing",
          "message" => "No such customer: cus_nonexistent"
        }
      })
    else
      conn
    end
  end)

  assert {:error, %{status: 404}} = Client.read("cus_nonexistent")
end

test "handles error using fixture" do
  Mock.stub(fn conn ->
    if conn.method == "POST" and conn.request_path == "/v1/customers" do
      error = Fixtures.load(:error_400)
      conn
      |> Plug.Conn.put_status(400)
      |> Mock.json(error)
    else
      conn
    end
  end)

  {:error, response} = Client.create(:customers, %{})
  assert response.status == 400
  assert response.body["error"]["code"] == "parameter_invalid_empty"
end

Pattern Matching on Multiple Requests

You can handle multiple request patterns in a single stub:

test "handles multiple operations" do
  Mock.stub(fn conn ->
    case {conn.method, conn.request_path} do
      {"GET", "/v1/customers/" <> id} ->
        Mock.json(conn, %{"id" => id, "email" => "#{id}@example.com"})

      {"POST", "/v1/customers"} ->
        Mock.json(conn, %{"id" => "cus_new", "email" => "new@example.com"})

      {"DELETE", "/v1/customers/" <> id} ->
        Mock.json(conn, %{"id" => id, "deleted" => true, "object" => "customer"})

      _ ->
        conn
    end
  end)

  {:ok, read_response} = Client.read("cus_123")
  assert read_response.body["id"] == "cus_123"

  {:ok, create_response} = Client.create(:customers, %{email: "new@example.com"})
  assert create_response.body["id"] == "cus_new"

  {:ok, delete_response} = Client.delete("cus_123")
  assert delete_response.body["deleted"] == true
end

Available Fixtures

See PinStripe.Test.Fixtures for the full list of available fixtures:

• :customer - A Stripe customer object
• :charge - A Stripe charge object
• :payment_intent - A Stripe payment intent object
• :refund - A Stripe refund object
• :error_400, :error_401, :error_403, :error_404, etc. - Various error responses

All fixtures can be customized with keyword options that override specific fields.