Testing the unhappy path: errors, timeouts and failures

TL;DR

Difficulty: Intermediate

Most test suites only prove the happy path. Research on real production failures found 92% of catastrophic ones began with an error the software had already detected and then handled badly.

  • Write the failing case first: assert the exact error class and the sentence the customer reads.
  • Simulate what you cannot cause: stub the network (WebMock), use the provider's test cards, move the clock (travel_to), make dependencies raise.
  • Test that retries happen and that they stop, and that a double click charges once.
  • Treat a payment timeout as unknown, never as failed.
  • Worked example: five unhappy path tests for a tea shop checkout.

My tests pass when everything works. How do I know what happens when it doesn't? This chapter answers that with real tests: declined cards, timeouts, double submissions, stock that runs out at the wrong moment and an email server that is down, each one written before the code that handles it.

Your tests pass. That proves less than you think.

Most test suites answer one question: does the software work when everything goes right? The customer has a valid card, the payment provider answers in 200 milliseconds, the tea is in stock, the email server is awake. That route through the code is called the happy path.

The unhappy path is everything else. The card is declined. The provider takes 40 seconds and then says nothing at all. The customer presses Pay twice because the button looked stuck. The last tin of Earl Grey sold to someone else while this basket sat open over lunch. The mail server is down for maintenance. None of these are exotic. On a shop that takes payments every day, all of them happen, and the question is only whether the software was told what to do when they do.

This chapter is about proving that, with tests, before a customer finds out for you. It builds on the test first loop from chapter one and on the error handling patterns from chapter six. Chapter six showed how to write code that handles failure. This chapter shows how to know that it does.

The evidence for bothering is unusually clear. A team at the University of Toronto studied 198 real, user reported failures in five widely used distributed systems, including Cassandra, HBase and Redis. Of the 48 failures that took the whole service down, 92% were the result of incorrect handling of errors that the software had already detected and signalled. In 58% of those catastrophic failures, the fault could easily have been found by simple testing of the error handling code. And 35% came down to three trivial patterns: an error handler that was empty or only wrote a log line, a handler that caught far too broad a class of error and shut everything down, or a handler that still said "TODO"1.

Read that again in plain words. The software saw the problem coming. Somebody wrote code for it. Nobody ever ran that code. That is the unhappy path, and that is why it needs its own tests.

Example: the one test Corrib Tea already has

Corrib Tea is an online tea shop in Galway. It sells loose tea and monthly subscriptions, takes card payments through a payment provider, offers discount codes, tracks stock and sends order emails. Its developer, Priya, has one checkout test, and it looks like this:

it "places an order" do
  stub_payment_succeeds
  order = checkout
  expect(order.status).to eq("paid")
end

It passes, every time, and that feels grand. Now ask it five questions. What happens if the card is declined? If the provider never answers? If the same order arrives twice? If the stock ran out a minute ago? If the confirmation email cannot be sent? The test has no opinion on any of them. It proves the shop works on a good day, and only on a good day. By the end of this chapter, Priya will have a test for each of those five questions, written before the code that answers it.

Rare failures are not rare once you multiply

A failure that happens "almost never" sounds safe to ignore. The trouble is that almost never, multiplied by a busy year, is a number you can count. The expected number of times something goes wrong is simply how often you try, times the chance it goes wrong each time (Foundations: expected value):

E=n⋅pE = n \cdot p

where EE is the expected number of failures in the period, nn is the number of attempts in that period (here, card payments), and pp is the probability that a single attempt fails in this particular way.

The same sum works for every unhappy path: declines, timeouts, double clicks, stock races. Each one is small, and each one, multiplied, turns into a handful of real customers with a real problem.

Example: ten timeouts a year at Corrib Tea

These numbers are invented for the example. Say Corrib Tea takes 20,000 card payments a year, and one payment in 2,000 runs into a network timeout between the shop and the payment provider. So n=20000n = 20000 and p=12000=0.0005p = \frac{1}{2000} = 0.0005.

E=20000⋅0.0005=10E = 20000 \cdot 0.0005 = 10

So E=10E = 10. Ten times a year, a customer presses Pay and the shop does not know whether the money moved. If the code has never been tested for that moment, those ten customers get whatever the code happens to do: perhaps an error page, perhaps a second charge when they try again, perhaps an order that was paid for and never shipped. Ten is not a lot, in fairness. It is ten reviews, ten support emails and possibly ten refunds, every year, for a situation that one test would have settled.

Write the failing case first

The test first loop from chapter one works the same way for errors as for features. You describe the failure you expect, watch the test fail, then write just enough code to make it pass. The only difference is what the test asserts: not that a value comes back, but that the right error is raised, with the right message, and that nothing else changed on the way.

Both common Ruby test libraries have a direct way to say "this should raise". In Minitest it is assert_raises, which also returns the exception so you can check its message2. In RSpec it is the raise_error matcher, which takes the error class and, optionally, the message or a pattern for it3. Always name the class. A bare raise_error with no class passes for any error at all, including a typo in your own code, so it can go green for exactly the wrong reason.

Example: a discount code that has been used up

Corrib Tea gives out a code, WELCOME5, that may be used 100 times. Priya starts with the failure, in Minitest:

class DiscountCodeTest < ActiveSupport::TestCase
  test "a code that has been used up is refused" do
    code = DiscountCode.new(code: "WELCOME5", percent_off: 5, max_uses: 100, uses: 100)

    error = assert_raises(DiscountCode::UsedUp) { code.apply_to(4_000) }

    assert_equal "WELCOME5 has already been used the maximum number of times.", error.message
  end
end

Line by line: she builds a code that has already been used 100 times out of 100. She asks it to apply itself to a basket of 4,000 cent, which is €40 (money in cent avoids rounding surprises). assert_raises expects that call to raise DiscountCode::UsedUp and hands back the error. The last line checks the message, because that text will reach a customer.

She runs it. It fails with NameError: uninitialized constant DiscountCode::UsedUp. That is red, but for the wrong reason: the error class does not exist yet, so the test never reached the question it asks. She adds one line to the model, UsedUp = Class.new(StandardError), and runs it again. Now it fails with "DiscountCode::UsedUp expected but nothing was raised". That is red for the right reason. Only now does she write the rule:

class DiscountCode < ApplicationRecord
  UsedUp = Class.new(StandardError)

  def apply_to(subtotal_cents)
    raise UsedUp, "#{code} has already been used the maximum number of times." if uses >= max_uses

    subtotal_cents - (subtotal_cents * percent_off / 100)
  end
end

Green. The same test in RSpec would read expect { code.apply_to(4_000) }.to raise_error(DiscountCode::UsedUp, /WELCOME5/). Either way, the failure is now part of the specification, and it cannot quietly disappear in a later change.

Check what the customer sees, not only what the code raises

An exception is a message from your code to your code. The customer never sees Stripe::CardError, and must not. Somewhere between the error and the screen, the shop translates it into words a person can act on: what happened, whether money moved, and what to do next. That translation is code too, and it breaks like any other code. A test of the unhappy path is only complete when it checks both ends: the right error inside, and the right sentence outside, with no internals leaking through.

Example: the declined card, as the customer reads it

Priya writes a request spec. It sends a real HTTP request to the shop's checkout endpoint and reads the page that comes back. The payment provider is replaced by a stub, which the next section explains, that answers "card declined".

RSpec.describe "Checkout", type: :request do
  it "tells the customer plainly when the card is declined" do
    stub_card_declined

    post checkout_path, params: { payment_method: "pm_test" }
    follow_redirect!

    expect(response.body).to include("Your card was declined. Nothing has been charged.")
    expect(response.body).not_to include("CardError")
  end
end

The first expectation checks the sentence the customer needs: what happened, and the one fact that stops a panicked phone call, that no money left the account. The second expectation is the safety net. If a future change lets the raw exception name leak onto the page, this test goes red. Wording is a design decision, so the exact sentence comes from whoever owns the shop's voice, and the test holds it in place.

Simulating the failures you cannot cause on demand

You cannot ask the payment provider to have an outage at 10am for your test run. You cannot make the clock strike midnight on cue, or fill the server's disk. So the trick of unhappy path testing is simulation: replacing the real world, for the length of one test, with a version that fails exactly the way you need. There are four tools for this, and each fits a different kind of failure.

Stub the network

A stub replaces a real network call with a canned answer. In Ruby, the WebMock library intercepts HTTP requests made by the common clients and lets you decide what comes back: a normal response, an error status, a raised exception, or a timeout, using to_return, to_raise and to_timeout4. Switch off real connections in the test setup with WebMock.disable_net_connect!(allow_localhost: true) and any request you forgot to stub fails loudly, so a test can never reach a real server by accident.

Stubs are fast and repeatable, so they run on every commit. Their weakness is that they only know what you told them. If the real provider changes its answers, your stub keeps telling the old story. That is what the next tool is for.

Example: the courier does not answer

Corrib Tea asks a courier's API for a delivery price in the basket. If the courier does not answer, the shop should not freeze. It should show its flat rate of €3.95 and let the customer carry on.

RSpec.describe ShippingQuote do
  it "falls back to the flat rate when the courier does not answer" do
    stub_request(:get, %r{\Ahttps://api\.courier\.example/rates}).to_timeout

    quote = ShippingQuote.for(eircode: "H91 AB12", weight_grams: 250)

    expect(quote.price_cents).to eq(395)
    expect(quote).to be_fallback
  end
end

The first line tells WebMock that any GET to the courier's rates address should behave like a server that never answers. The second line asks for a quote for a 250 gram parcel to a Galway Eircode. The expectations say what Priya decided should happen: the flat rate, and a flag that this is a fallback, so the shop can log it and the page can say "standard delivery". Writing the test forced the decision. Before it, nobody had said what a missing courier means.

Use the provider's own test cards

Payment providers know that everyone needs to test declines, so they publish test cards that fail on purpose. Stripe's sandbox, for example, documents a card that is always declined (4000 0000 0000 0002, or the PaymentMethod pm_card_visa_chargeDeclined), one declined for insufficient funds (4000 0000 0000 9995) and one declined as expired (4000 0000 0000 0069, or pm_card_chargeDeclinedExpiredCard), next to the card that always succeeds (4242 4242 4242 4242)5. Its documentation also lists which Ruby exception each kind of failure raises: Stripe::CardError for payment errors, Stripe::APIConnectionError for network problems, and so on6.

Tests against the sandbox talk to the real provider over the internet, so they are slower and occasionally flaky. They belong in a separate suite that runs nightly or before a release, not on every save. Their job is to catch the day your stubs and the real provider stop agreeing. A library such as VCR can record real sandbox answers and replay them in later runs, which makes them fast and repeatable7, with one caution: a recording is a snapshot, so record again on a schedule, or it becomes another stub telling an old story.

Example: Corrib Tea's nightly sandbox check

RSpec.describe "Stripe sandbox declines", :sandbox do
  before { WebMock.allow_net_connect! }
  after  { WebMock.disable_net_connect!(allow_localhost: true) }

  %w[pm_card_visa_chargeDeclined pm_card_chargeDeclinedExpiredCard].each do |card|
    it "turns #{card} into a declined checkout" do
      expect { checkout(payment_method: card) }.to raise_error(Checkout::Declined)
    end
  end
end

The :sandbox tag lets Priya exclude this file from the normal run (config.filter_run_excluding :sandbox in the RSpec configuration) and run it on its own with bundle exec rspec --tag sandbox every night. The before and after lines open the network for these tests only and close it again. The loop runs the same check for two of the documented test cards: each one must come back as the shop's own Checkout::Declined error, not a raw provider exception and not a success.

Move the clock

Anything that depends on the date fails at a boundary: a discount that ends at midnight, a subscription that renews on the first of the month, a card that expires at the end of a month. Tests that use the real clock pass today and fail on some later day for no visible reason. Rails solves this with travel_to, which stubs Time.now, Date.today and DateTime.now so that, inside a block, the test lives at exactly the moment you choose8.

The rule for picking that moment is called boundary value testing: test the last moment that should work and the first moment that should not, because off by one mistakes live exactly there.

Example: the spring code ends at midnight

test "SPRING10 works until the last second of 31 March" do
  code = DiscountCode.new(code: "SPRING10", percent_off: 10, max_uses: 500, uses: 0,
                          expires_at: Time.zone.parse("2026-03-31 23:59:59"))

  travel_to Time.zone.parse("2026-03-31 23:59:59") do
    assert_equal 3_600, code.apply_to(4_000)
  end

  travel_to Time.zone.parse("2026-04-01 00:00:00") do
    assert_raises(DiscountCode::Expired) { code.apply_to(4_000) }
  end
end

The first block puts the test one second before the end: 10% off €40 must give €36, which is 3,600 cent. The second block puts it one second later, where the same code must be refused. Two moments, one second apart, and the whole rule is pinned down. If someone later writes >= where > belongs, this test notices before a customer does.

Make the dependency raise

Some failures are not on the network at all: the disk is full, a file is missing, a library throws. Here the simplest tool is a stub on your own object that raises the real exception the real failure would raise. In RSpec that is allow(SomeClass).to receive(:method).and_raise(SomeError).

Example: the invoice cannot be written

After payment, Corrib Tea writes a PDF invoice to storage. If the disk is full, Ruby raises Errno::ENOSPC. Priya's decision: the order stays paid, the invoice is marked as failed so it can be made again, and nobody's money depends on a PDF.

RSpec.describe GenerateInvoiceJob do
  it "keeps the order paid and flags the invoice when the disk is full" do
    order = Order.create!(status: "paid", email: "ada@example.com")
    allow(InvoicePdf).to receive(:write).and_raise(Errno::ENOSPC)

    GenerateInvoiceJob.perform_now(order)

    expect(order.reload.status).to eq("paid")
    expect(order.invoice_status).to eq("failed")
  end
end

The stub makes the PDF writer behave exactly like a full disk. The job runs. The expectations check the two things that matter: the order was not touched, and the failure was recorded where someone will see it. This is precisely the kind of handler the Toronto study found failing in production: one that only logged, or caught too much1. Now it has been run at least once.

Tap or click to open full screen and move around

Testing retries: the second attempt happens, and the last one stops

Chapter six explained retries: when a failure is temporary, try again a little later. A retry is unhappy path code with two ways to go wrong. It may never retry, so a short blip becomes a lost email. Or it may retry forever, so a permanent problem becomes an endless loop nobody hears about. A good retry test checks both ends: that a failure schedules another attempt, and that after the last attempt a person is told.

In Rails, background jobs declare this with retry_on, and the Rails guides note that a failed job is not retried unless you configure it9. The rspec-rails gem can then check that a job was put back on the queue with the have_enqueued_job matcher10, which needs the test queue adapter (config.active_job.queue_adapter = :test in the test environment).

Example: the order email that will not send

class SendOrderConfirmationJob < ApplicationJob
  retry_on Net::OpenTimeout, Net::SMTPServerBusy, attempts: 5 do |job, _error|
    AdminMailer.confirmation_failed(job.arguments.first).deliver_later
  end

  def perform(order)
    OrderMailer.confirmation(order).deliver_now
  end
end

The job sends the confirmation email. If the mail server times out or says it is busy, Rails tries again later, up to five attempts in total. If the fifth attempt fails too, the block runs and Priya gets an email of her own saying which order is missing its confirmation. Now the tests:

RSpec.describe SendOrderConfirmationJob do
  let(:order) { Order.create!(status: "paid", email: "ada@example.com") }

  before { allow(OrderMailer).to receive(:confirmation).and_raise(Net::OpenTimeout) }

  it "tries again later when the mail server does not answer" do
    expect { described_class.perform_now(order) }
      .to have_enqueued_job(described_class).with(order)
  end

  it "stops after five attempts and tells a person" do
    job = described_class.new(order)
    job.executions = 4

    expect { job.perform_now }.to have_enqueued_mail(AdminMailer, :confirmation_failed)
  end
end

The before line makes every attempt to build the email raise a timeout, as if the mail server were down. The first test runs the job once and expects to find the same job back on the queue for the same order. The second test pretends four attempts have already failed by setting executions to 4, runs the fifth, and expects the alert email instead of another retry. Two short tests, and the retry policy is now a fact rather than a hope.

Fault injection: break things on purpose, in small doses

Chaos engineering is the practice of experimenting on a system to build confidence that it can withstand turbulent conditions in production11. Netflix made the idea famous with Chaos Monkey, a tool that randomly terminates server instances in production so that engineers have to build services that survive it12. The published principles include forming a hypothesis about normal behaviour, varying real world events and keeping the blast radius small11.

A tea shop does not need to switch off servers at random. But the idea scales down beautifully. Fault injection means deliberately making one dependency fail, in a controlled test, and watching what the whole system does. In a browser test with Playwright, you can intercept any request the page makes and abort it with a named network error such as timedout or connectionrefused, or answer it with any status you like13. That lets you test the front end's unhappy path without touching a server.

Example: the stock check times out in the browser

Corrib Tea's basket page asks the shop's own API whether everything is still in stock. Priya wants to know what a customer sees when that call times out.

import { test, expect } from '@playwright/test';

test('the basket explains itself when the stock check times out', async ({ page }) => {
  await page.route('**/api/stock/**', (route) => route.abort('timedout'));

  await page.goto('/basket');

  await expect(page.getByRole('alert')).toHaveText(
    "We couldn't check stock just now. Your basket is saved, so try again in a minute."
  );
  await expect(page.getByRole('button', { name: 'Go to checkout' })).toBeEnabled();
});

page.route catches every request to the stock API and aborts it as a timeout, the same failure a slow network would cause. The test then opens the basket and checks two things: an alert with a calm, useful sentence (found by its accessible role, which also proves a screen reader will announce it), and that the checkout button still works. That second check is deliberate. The stock is checked again, properly, at payment, as test four below will prove, so a failed check here should never trap a customer in the basket.

Boundary values and property based testing

You have already met boundary values: test just inside and just outside every limit. For a percentage discount the interesting inputs are 0, 1, 99, 100 and 101. For a quantity they are 0, 1 and the stock level. Most off by one mistakes are caught by these few cases.

Property based testing goes one step further. Instead of choosing inputs by hand, you state a rule that must hold for every input, and the library generates hundreds of random inputs to try to break it. The idea comes from QuickCheck, a tool for Haskell published by Koen Claessen and John Hughes in 200014. In JavaScript and TypeScript, the fast-check library does the same, and when it finds a failing input it shrinks it down to the smallest input that still fails, so the bug report is readable15.

Example: a discount never makes the total negative

Corrib Tea's front end calculates the basket total. Whatever the basket and whatever the discount, two things must always be true: the total is never below zero, and never above the subtotal.

import { test } from 'vitest';
import fc from 'fast-check';
import { basketTotal } from './basketTotal';

test('a discount never makes the total negative or larger', () => {
  const line = fc.record({
    priceCents: fc.integer({ min: 1, max: 10_000 }),
    quantity: fc.integer({ min: 1, max: 20 }),
  });

  fc.assert(
    fc.property(fc.array(line), fc.integer({ min: 0, max: 100 }), (lines, percentOff) => {
      const subtotal = lines.reduce((sum, l) => sum + l.priceCents * l.quantity, 0);
      const total = basketTotal(lines, percentOff);
      return total >= 0 && total <= subtotal;
    })
  );
});

line describes one random basket line: a price between 1 cent and €100 and a quantity between 1 and 20. fc.array(line) builds random baskets from those lines, including the empty basket, which hand written tests often forget. The property runs for each generated basket and each discount from 0% to 100%, and returns true only if both rules hold. If someone later lets a fixed €5 voucher apply to a €3 basket, the library will find a basket that goes negative and report the smallest one it can.

Worked example: five unhappy path tests for Corrib Tea's checkout

Now everything comes together on the part of the shop that matters most: the critical path from pressing Pay to a confirmed order. Priya writes five tests, one for each question from the start of the chapter, each one before the code that makes it pass.

First, the shared setup. A small helper file holds the stubs, so each test reads like a sentence:

# spec/support/stripe_stubs.rb
module StripeStubs
  PAYMENT_INTENTS = "https://api.stripe.com/v1/payment_intents"

  def stub_payment_succeeds
    stub_request(:post, PAYMENT_INTENTS).to_return(
      status: 200, body: { id: "pi_test", object: "payment_intent", status: "succeeded" }.to_json
    )
  end

  def stub_card_declined
    stub_request(:post, PAYMENT_INTENTS).to_return(
      status: 402, body: { error: { type: "card_error", code: "card_declined",
                                    message: "Your card was declined." } }.to_json
    )
  end
end

Both helpers stub the address where the shop creates a payment. The first returns a successful payment. The second returns the status 402 and the error body a card decline produces, which the Stripe library turns into Stripe::CardError6. And the top of the spec file:

RSpec.describe Checkout do
  include StripeStubs

  let(:earl_grey) { Product.create!(name: "Earl Grey 100g", price_cents: 650, stock: 5) }
  let(:basket) { Basket.create!.tap { |b| b.lines.create!(product: earl_grey, quantity: 2) } }

  def checkout(key: "order-7f3a")
    Checkout.new(basket:, payment_method: "pm_test", idempotency_key: key).call
  end

Five tins of Earl Grey in stock, two in the basket, and a checkout method that runs the whole checkout with an idempotency key, a unique label for this one attempt to pay. The key matters in test three.

Test one: the card is declined

  it "does not take the order when the card is declined" do
    stub_card_declined

    expect { checkout }.to raise_error(Checkout::Declined, "Your card was declined.")
    expect(earl_grey.reload.stock).to eq(5)
    expect(Order.last.status).to eq("declined")
  end

The provider says no. The shop must raise its own Checkout::Declined error with a message fit for the customer, put the two reserved tins back on the shelf (stock back to 5), and record the attempt as declined so Priya can see it. Without the stock check, a run of declined cards would slowly make the shop look sold out.

Test two: the provider does not answer

  it "marks the payment as unknown when the provider does not answer" do
    stub_request(:post, StripeStubs::PAYMENT_INTENTS).to_timeout

    expect { checkout }.to raise_error(Checkout::PaymentUnknown)
    expect(Order.last.status).to eq("payment_unknown")
    expect(ConfirmPaymentJob).to have_been_enqueued.with(Order.last)
  end

This is the most important test of the five, and the one most shops lack. A timeout does not mean the payment failed. It means the shop does not know. Stripe's own documentation says to treat the result of a connection error as indeterminate, neither success nor failure, and to find out by retrying with the same idempotency key or by checking the payment's status6. So the test demands exactly that: no "declined" message to the customer, an order marked as unknown with its tins still reserved, and a background job queued to find out what really happened. The customer is told the payment is being confirmed and an email will follow.

Test three: the same order arrives twice

  it "charges once when the same order is submitted twice" do
    stub_payment_succeeds

    first = checkout(key: "order-7f3a")
    second = checkout(key: "order-7f3a")

    expect(second).to eq(first)
    expect(a_request(:post, StripeStubs::PAYMENT_INTENTS)
      .with(headers: { "Idempotency-Key" => "order-7f3a" })).to have_been_made.once
    expect(earl_grey.reload.stock).to eq(3)
  end

The customer double clicks Pay, or the browser resends the form. Both requests carry the same key, because the key is created once when the checkout page loads. The test expects the second call to return the first order rather than create a new one, the provider to be asked exactly once (WebMock counts the requests4), the key to be sent along in the Idempotency-Key header, and only two tins to leave the shelf. That header is the provider's own protection: Stripe stores the result of the first request made with a key and returns that saved result to any retry with the same key, so even a retry that slips past the shop cannot charge twice16. Two layers, both tested.

Test four: the tea sold out while the basket waited

  it "stops before charging when the stock ran out in the meantime" do
    stub_payment_succeeds
    earl_grey.update!(stock: 1) # someone else bought four tins over lunch

    expect { checkout }.to raise_error(Checkout::OutOfStock, /Earl Grey/)
    expect(a_request(:post, StripeStubs::PAYMENT_INTENTS)).not_to have_been_made
    expect(Order.count).to eq(0)
  end

The basket wants two tins, only one is left. The shop must notice before it takes any money, name the tea that ran out, and leave no half made order behind. The middle expectation is the one that protects the customer: the provider must never be called. Charging first and refunding later costs fees, trust and a support email.

Test five: the email service is down

  it "keeps the order paid when the confirmation email cannot be sent yet" do
    stub_payment_succeeds

    order = checkout

    expect(order.status).to eq("paid")
    expect(SendOrderConfirmationJob).to have_been_enqueued.with(order)
  end
end

The checkout itself never talks to the mail server. It puts the email job on the queue and finishes. That is the design this test enforces: an email outage must never turn a paid order into an error page. The job's own retry and alert are already covered by the tests in the retries section above.

The code that makes the five tests pass

Priya wrote these tests one at a time, each red before green. The resulting checkout, trimmed to its shape, looks like this:

class Checkout
  Declined = Class.new(StandardError)
  PaymentUnknown = Class.new(StandardError)
  OutOfStock = Class.new(StandardError)

  def call
    existing = Order.find_by(idempotency_key: @key)
    return existing if existing

    order = reserve_stock_and_create_order # raises OutOfStock before any charge
    charge(order)
    order.update!(status: "paid")
    SendOrderConfirmationJob.perform_later(order)
    order
  end

  private

  def charge(order)
    @stripe.v1.payment_intents.create(payment_params(order), { idempotency_key: @key })
  rescue Stripe::CardError => e
    order.release_stock!
    order.update!(status: "declined")
    raise Declined, e.message
  rescue Stripe::APIConnectionError
    order.update!(status: "payment_unknown")
    ConfirmPaymentJob.perform_later(order)
    raise PaymentUnknown
  end
end

Each line answers one test. The early return answers test three, together with a unique index on idempotency_key in the database, so that two truly simultaneous requests cannot both create an order. The stock reservation, which locks each product row while it checks and reduces the stock, answers test four. The two rescue clauses answer tests one and two, each catching one specific error class and nothing broader, which is precisely the mistake the Toronto study found behind so many outages1. The job on the last lines answers test five.

Tap or click to open full screen and move around

A checklist of unhappy paths for any checkout

Every shop is different, but the failures at a checkout repeat themselves. Before a checkout counts as done, each of these deserves a test, or a written and agreed reason for not having one:

  • The card is declined, for each decline reason the shop words differently.
  • The payment provider times out, or the connection drops after the request was sent.
  • The provider returns a server error.
  • The same payment request is sent twice: double click, browser resend, a retry.
  • Stock runs out between the basket and the payment.
  • A discount code is expired, used up, or not valid for this basket.
  • The basket total is zero, or a discount would push it below zero.
  • The customer's session expires halfway through.
  • The confirmation email cannot be sent.
  • The invoice or receipt cannot be generated or stored.
  • A webhook from the provider arrives late, twice, or before the order exists.
  • An external lookup (courier, tax, address) is slow or down.

Each line is a question for the business as much as for the code. What should the customer read? Is money involved? Who needs to know? The test is where the answer gets written down for good.

Example: Priya runs the checklist

Priya goes through the list for Corrib Tea. The five tests above cover lines one, two, four, five and nine. The shipping stub and the Playwright test cover line twelve. Two lines have no test yet. A session that expires on the payment page currently shows a generic error, so she writes a failing request spec for it and agrees the wording with the owner: "Your session timed out, but your basket is saved." And the provider's webhook can arrive before the shop has saved the order, which would make the shop ignore a real payment. That one is on the critical path, so it goes first. One afternoon, two new red tests, and two failures that would have reached customers are now handled on purpose.

Conclusion

A suite that only tests the happy path tells you the software works when nothing goes wrong, which is the one day you did not need telling. The failures that cost money are the expected ones: declines, timeouts, double clicks, races and outages. Research on real production failures finds that most catastrophic ones start with an error the software already detected and then handled badly, in code that simple tests would have exercised1.

So write the unhappy path test first, the same way as any other: name the failure, watch it fail for the right reason, then make it pass. Simulate what you cannot cause: stub the network, use the provider's test cards, move the clock, make dependencies raise. Test that retries happen and that they stop. Check both the error inside and the sentence outside. And treat a timeout on a payment as unknown, never as failed.

I work test first, and for a checkout that includes the failures: the critical path is not guarded until its unhappy branches are tested too. If you want to know which of these twelve checks your own shop would pass today, that is a good first hour of work. The next chapter turns to the tools: how to make an AI coding assistant work test first, every time, for the whole project.

If you want to know what your checkout does on its worst day, book the free workshop: we run your critical path through the unhappy path checklist together, no bother, and the first two weeks of work are on me.

Sources

  1. 1.

    Ding Yuan, Yu Luo, Xin Zhuang, Guilherme Renna Rodrigues, Xu Zhao, Yongle Zhang, Pranay U. Jain and Michael Stumm, Simple testing can prevent most critical failures: an analysis of production failures in distributed data intensive systems, 11th USENIX Symposium on Operating Systems Design and Implementation (OSDI), 2014, https://www.usenix.org/conference/osdi14/technical-sessions/presentation/yuan

  2. 2.

    Minitest, Minitest::Assertions documentation (assert_raises), seattlerb, https://docs.seattlerb.org/minitest/Minitest/Assertions.html

  3. 3.

    RSpec, raise_error matcher, rspec-expectations 3.13 documentation, https://rspec.info/features/3-13/rspec-expectations/built-in-matchers/raise-error/

  4. 4.

    Bartosz Blimke and contributors, WebMock: library for stubbing and setting expectations on HTTP requests in Ruby, README, GitHub, https://github.com/bblimke/webmock

  5. 5.

    Stripe, Testing: test card numbers and declined payments, Stripe documentation, https://docs.stripe.com/testing

  6. 6.

    Stripe, Error handling (Ruby): error types, payment errors and connection errors, Stripe documentation, https://docs.stripe.com/error-handling?lang=ruby

  7. 7.

    VCR contributors, VCR: record your test suite's HTTP interactions and replay them, README, GitHub, https://github.com/vcr/vcr

  8. 8.

    Ruby on Rails, ActiveSupport::Testing::TimeHelpers (travel_to, freeze_time, travel_back), Rails API documentation, https://api.rubyonrails.org/classes/ActiveSupport/Testing/TimeHelpers.html

  9. 9.

    Ruby on Rails, Active Job basics: retrying or discarding failed jobs, Rails Guides, https://guides.rubyonrails.org/active_job_basics.html

  10. 10.

    RSpec, have_enqueued_job matcher, rspec-rails 7.1 documentation, https://rspec.info/features/7-1/rspec-rails/matchers/have-enqueued-job-matcher/

  11. 11.

    Principles of Chaos Engineering, principlesofchaos.org, last updated March 2019, https://principlesofchaos.org/

  12. 12.

    Netflix, Chaos Monkey documentation, GitHub Pages, https://netflix.github.io/chaosmonkey/

  13. 13.

    Microsoft, Playwright: class Route (route.abort and its error codes), Playwright documentation, https://playwright.dev/docs/api/class-route

  14. 14.

    Koen Claessen and John Hughes, QuickCheck: a lightweight tool for random testing of Haskell programs, Proceedings of the ACM SIGPLAN International Conference on Functional Programming (ICFP), 2000, https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf

  15. 15.

    fast-check, Introduction: property based testing for JavaScript and TypeScript, fast-check documentation, https://fast-check.dev/docs/introduction/

  16. 16.

    Stripe, Idempotent requests, Stripe API reference, https://docs.stripe.com/api/idempotent_requests