Automatically generates and caches Stripe API fixtures for testing.

Fixtures are generated using your Stripe account's API version via the Stripe CLI and cached in test/fixtures/stripe/. The API version is tracked in .api_version.

⚠️ Important: Side Effects

Fixture generation creates real test data in your Stripe account.

• Resources (customers, products, etc.) are created in test mode
• Objects are marked with "PinStripe Test Fixture" for identification
• Only test mode API keys (starting with sk_test_) are allowed
• Consider committing fixtures to git to avoid regenerating

Requirements

• Stripe CLI installed: brew install stripe/stripe-cli/stripe
• Stripe CLI authenticated: stripe login
• Test mode API key configured (starts with sk_test_)

Quick Start

Configuration

# config/test.exs
config :pin_stripe,
  stripe_api_key: System.get_env("STRIPE_SECRET_KEY")

Basic Usage

# In your test
test "creates a customer" do
  # Load/generate a customer fixture (use atoms for API resources)
  customer = PinStripe.Test.Fixtures.load(:customer)

  # Use with Req.Test
  Req.Test.stub(PinStripe, fn conn ->
    Req.Test.json(conn, customer)
  end)

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

Customizing Fixtures

Generate fixtures with specific attributes by passing options:

# Customer with specific email (atoms for API resources)
customer = PinStripe.Test.Fixtures.load(:customer,
  email: "alice@example.com",
  name: "Alice Smith"
)

# Customer with metadata
customer = PinStripe.Test.Fixtures.load(:customer,
  metadata: %{user_id: "123", plan: "premium"}
)

# Webhook event with custom data (strings for webhook events - they have dots)
event = PinStripe.Test.Fixtures.load("customer.created",
  data: %{object: %{email: "custom@example.com"}}
)

Each unique set of options creates a separate cached fixture file. The filename includes a hash of the options for uniqueness:

test/fixtures/stripe/
  customer.json              # Base customer
  customer-a3f2b9c1.json    # Customized customer

API Version Management

Fixtures match your Stripe account's default API version at the time they're first generated. The version is stored in test/fixtures/stripe/.api_version.

When you upgrade your Stripe account's API version, run the sync task to clear old fixtures and regenerate them with the new version:

mix pin_stripe.sync_api_version

This task:

• Detects your account's current API version
• Compares it with the cached version
• Clears all fixtures if the version changed
• Updates the .api_version file

Supported Fixtures

API Resources (Atoms)

• :customer - Customer objects
• :product - Product objects
• :price - Price objects
• :subscription - Subscription objects
• :invoice - Invoice objects
• :charge - Charge objects (one-time payments)
• :payment_intent - PaymentIntent objects (modern payment flow)
• :refund - Refund objects

Webhook Events (Strings - they have dots)

• "customer.created", "customer.updated", "customer.deleted"
• "customer.subscription.created", "customer.subscription.updated", "customer.subscription.deleted"
• "invoice.paid", "invoice.payment_failed"

Error Responses (Atoms)

• :error_404 - Not found (resource_missing)
• :error_400 - Bad request (invalid_request_error)
• :error_401 - Unauthorized (authentication error)
• error_429 - Rate limit exceeded

Testing Best Practices

Commit Fixtures to Git

To avoid generating fixtures in CI or on every developer machine:

# Commit fixtures to version control
git add test/fixtures/stripe
git commit -m "Add Stripe test fixtures"

Use Base Fixtures and Modify

Instead of generating many custom fixtures:

# Load base fixture
customer = PinStripe.Test.Fixtures.load(:customer)

# Modify as needed in your test
customer = Map.put(customer, "email", "specific@test.com")

Clean Up Test Data

Objects created during fixture generation accumulate in your Stripe test account. They're marked with pinstripe_fixture: true metadata for easy identification.

To clean up manually:

# List PinStripe test objects
stripe customers list --limit 100 | grep "PinStripe Test Fixture"

# Delete a specific customer
stripe customers delete cus_xxx

Examples

Testing API Responses

test "handles customer creation" do
  fixture = PinStripe.Test.Fixtures.load(:customer)

  Req.Test.stub(PinStripe, fn conn ->
    Req.Test.json(conn, fixture)
  end)

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

Testing Webhook Handlers

test "handles customer.created webhook" do
  event = PinStripe.Test.Fixtures.load("customer.created")

  conn = build_webhook_conn(event)
  conn = MyAppWeb.StripeWebhookController.create(conn, event)

  assert conn.status == 200
end

Testing Error Handling

test "handles not found error" do
  error = PinStripe.Test.Fixtures.load(:error_404)

  Req.Test.stub(PinStripe, fn conn ->
    conn
    |> Plug.Conn.put_status(404)
    |> Req.Test.json(error)
  end)

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

Testing with Multiple Customers

test "handles multiple customers" do
  alice = PinStripe.Test.Fixtures.load(:customer, email: "alice@test.com")
  bob = PinStripe.Test.Fixtures.load(:customer, email: "bob@test.com")

  # Each gets cached separately
  assert alice["email"] == "alice@test.com"
  assert bob["email"] == "bob@test.com"
end