DEV Community: Billy Okeyo

Idempotency Explained: Building APIs That Survive Retries

Billy Okeyo — Thu, 25 Jun 2026 00:00:00 +0000

Imagine you're purchasing a product online.

You click the "Pay Now" button.

Nothing happens.

After a few seconds, you assume the request failed, so you click the button again.

And again.

A few minutes later, you discover you've been charged three times.

What happened?

From the user's perspective, the payment seemed to fail. From the server's perspective, however, it successfully processed every request it received.

This is one of the most common problems in distributed systems, and it's exactly why idempotency exists.

Whether you're building payment systems, booking platforms, inventory management software, or any API that changes data, retries are inevitable. Networks fail, clients time out, mobile connections drop, and users double-click buttons.

A well-designed API should survive these retries without creating duplicate side effects.

In this article, we'll explore what idempotency is, why it matters, and how to implement it in your own APIs.

What Is Idempotency?

In simple terms, an idempotent operation can be performed multiple times without changing the final result beyond the first successful execution.

For example:

Turn on the light.
Turn on the light again.
Turn on the light again.

The light is still ON.

Nothing new happened after the first request.

The final state remains the same.

That's idempotency.

Now compare it with this:

Deposit $100
Deposit $100
Deposit $100

Your account balance increases by $300.

This operation is not idempotent because every request changes the system.

Why Retries Happen

Many developers assume users only send one request.

Reality is different.

Requests are retried because of:

Slow internet connections
Gateway timeouts
Reverse proxies
Mobile network interruptions
Browser refreshes
Double-clicking buttons
Client retry mechanisms
Load balancers
Microservice communication failures

Imagine this timeline:

Client -------- POST /payments --------> API

             Payment succeeds

API -------- 200 OK --------X

(Response never reaches client)

Client waits...

Client retries.

POST /payments again.

The client believes the payment failed.

The server already completed it.

Without idempotency...

The payment happens twice.

HTTP Methods and Idempotency

HTTP itself distinguishes between idempotent and non-idempotent methods.

GET

GET /users/10

Read the user.

Call it once.

Call it 100 times.

Nothing changes.

Idempotent

PUT

PUT /users/10
{
   "name": "Billy"
}

Replacing the same resource repeatedly produces the same result.

Idempotent

DELETE

DELETE /users/10

Delete the user.

Deleting an already deleted user doesn't delete them twice.

The final state is still:

User does not exist.

Idempotent

POST

POST /orders

Create a new order.

Call it twice.

You now have two orders.

Not idempotent

This is why POST requests often require additional protection.

Why Payment APIs Use Idempotency Keys

Payment providers like Stripe popularized the use of Idempotency Keys.

The idea is simple.

The client generates a unique identifier.

Example:

Idempotency-Key:
6ab89d3b-acde-4d71-b20d-483d8d0ef091

Every retry sends the same key.

POST /payments

Idempotency-Key:
6ab89d3b-acde-4d71-b20d-483d8d0ef091

When the server receives the request:

Check if this key already exists.
If not, process the payment.
Save both the key and the response.
Return the response.

If the same request arrives again with the same key:

Instead of charging the customer again...

Return the previously stored response.

Client

POST /payments
Key: ABC123

↓

Server

Charge customer

↓

Store

ABC123 → Payment #456

↓

Return success

---

Retry

POST /payments
Key: ABC123

↓

Lookup

ABC123 exists

↓

Return Payment #456

No second charge.

Implementing Idempotency

A common workflow looks like this.

Step 1

Receive request.

POST /orders

Headers

Idempotency-Key:
XYZ987

Step 2

Search database.

SELECT *
FROM idempotency_keys
WHERE key = 'XYZ987'

Found?

Yes.

Return stored response.

Done.

Step 3

Not found?

Create the resource.

Create Order

Step 4

Store:

Key

Response

Status Code

Timestamp

Now every retry returns the same response.

Example in Node.js (Express)

app.post("/payments", async (req, res) => {
    const key = req.header("Idempotency-Key");

    const existing = await Idempotency.findOne({ key });

    if (existing) {
        return res.status(existing.status).json(existing.response);
    }

    const payment = await processPayment(req.body);

    await Idempotency.create({
        key,
        status: 201,
        response: payment,
    });

    return res.status(201).json(payment);
});

Python (FastAPI)

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/payments")
async def create_payment(request: Request):
    key = request.headers.get("Idempotency-Key")

    existing = await Idempotency.find_one(key=key)

    if existing:
        return JSONResponse(
            content=existing.response,
            status_code=existing.status,
        )

    body = await request.json()
    payment = await process_payment(body)

    await Idempotency.create(
        key=key,
        status=201,
        response=payment,
    )

    return JSONResponse(content=payment, status_code=201)

C# (ASP.NET Core)

app.MapPost("/payments", async (
    HttpRequest request,
    IdempotencyStore store,
    PaymentService payments) =>
{
    var key = request.Headers["Idempotency-Key"].ToString();

    var existing = await store.FindAsync(key);
    if (existing is not null)
    {
        return Results.Json(existing.Response, statusCode: existing.Status);
    }

    var body = await request.ReadFromJsonAsync<PaymentRequest>();
    var payment = await payments.ProcessAsync(body!);

    await store.CreateAsync(new IdempotencyRecord(key, 201, payment));

    return Results.Json(payment, statusCode: StatusCodes.Status201Created);
});

Go

func createPayment(w http.ResponseWriter, r *http.Request) {
    key := r.Header.Get("Idempotency-Key")

    existing, err := idempotency.FindOne(r.Context(), key)
    if err == nil && existing != nil {
        w.WriteHeader(existing.Status)
        json.NewEncoder(w).Encode(existing.Response)
        return
    }

    var body PaymentRequest
    if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    payment, err := processPayment(r.Context(), body)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }

    if err := idempotency.Create(r.Context(), IdempotencyRecord{
        Key:      key,
        Status:   http.StatusCreated,
        Response: payment,
    }); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }

    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(payment)
}

Laravel

Route::post('/payments', function (Request $request) {
    $key = $request->header('Idempotency-Key');

    $existing = Idempotency::where('key', $key)->first();

    if ($existing) {
        return response()->json($existing->response, $existing->status);
    }

    $payment = processPayment($request->all());

    Idempotency::create([
        'key' => $key,
        'status' => 201,
        'response' => $payment,
    ]);

    return response()->json($payment, 201);
});

The logic is surprisingly simple.

The complexity comes from storing and managing the keys correctly.

Where Should Idempotency Keys Be Stored?

Options include:

Database

Best for most applications.

Pros:

Persistent
Reliable
Easy to query

Cons:

Slightly slower

Redis

Excellent for high-volume APIs.

Pros:

Extremely fast
TTL support
Easy expiration

Many APIs automatically expire keys after 24 hours.

In-Memory

Useful only during development.

Not recommended for production.

Restarting the server loses everything.

Common Mistakes

Reusing Keys

Every logical operation should have its own unique key.

Bad:

ABC123

used today

used tomorrow

Good:

New checkout

↓

Generate new UUID

Ignoring Request Differences

Suppose the first request is:

$50

The retry is:

$500

Same key.

Different body.

The server should reject this request because the key is being reused for a different operation.

Never Expiring Keys

Keeping millions of old keys forever wastes storage.

Most APIs expire them after:

24 hours
48 hours
7 days

depending on business requirements.

Real-World Use Cases

Idempotency is valuable anywhere duplicate requests could have costly consequences.

Examples include:

Payment processing
Bank transfers
Order creation
Hotel reservations
Flight bookings
Ticket purchases
Subscription billing
Inventory updates
Webhook processing
Email sending
Message queues

If performing the same action twice could create an incorrect outcome, idempotency is worth considering.

When You Don't Need Idempotency

Not every endpoint needs an idempotency key.

For example:

GET /posts

No state changes.

No duplicates.

No problem.

Likewise, endpoints such as:

Search
Filtering
Reading reports
Viewing profiles

are already naturally idempotent.

Reserve idempotency mechanisms for operations where retries could create unintended side effects.

Final Thoughts

Idempotency isn't just an implementation detail—it's a reliability feature.

In distributed systems, retries are normal. Networks are unreliable, users click buttons more than once, and clients retry requests automatically. Instead of hoping those situations never happen, design your APIs to handle them gracefully.

By using idempotency keys, storing responses, validating retries, and choosing the right storage strategy, you can prevent duplicate orders, repeated payments, and other costly errors.

A resilient API isn't one that never receives duplicate requests.

It's one that produces the correct outcome even when duplicate requests inevitably arrive.

The next time you design a POST endpoint, ask yourself:

"What happens if this request is sent twice?"

If the answer is "something bad," it's probably time to add idempotency.

Debugging Is a Skill Nobody Teaches You

Billy Okeyo — Mon, 04 May 2026 00:00:00 +0000

You’ve been staring at the same bug for 2 hours.
You’ve restarted the server. Cleared cache. Added random console.logs.
Somehow… it still doesn’t work.

At some point, you stop coding and start guessing.

And that’s the real problem.

The issue isn’t the bug.
It’s that nobody actually teaches debugging as a skill.

The Way Most Developers Debug

Let’s be honest. Most of us learned debugging like this:

Sprinkle console.log everywhere
Change random lines and hope something works
Copy-paste error messages into Google
Restart everything “just in case”

It sometimes works.

But it’s slow, frustrating, and unreliable.

It’s not debugging.

It’s trial and error disguised as progress.

What Debugging Actually Is

Here’s the mindset shift that changes everything:

Debugging is not about fixing code.
It’s about finding where your mental model diverges from reality.

You think the system works one way.

Reality says otherwise.

Your job is to close that gap.

The Debugging Mindset

Before tools, before techniques, this is what matters most.

1. Assume Your Assumptions Are Wrong

If something doesn’t work, at least one thing you believe is false.

Your job is to find it.

2. Narrow the Problem Space

Bad debugging:

“Something is wrong with the app”

Good debugging:

“The issue happens only when this function runs after login”

3. Reproduce Before Fixing

If you can’t reliably reproduce the bug, you don’t understand it.

And if you don’t understand it, your fix is luck—not skill.

4. One Change at a Time

If you change 5 things and it works…
which one fixed it?

You don’t know.

That’s how bugs come back later.

5. Understand Before You Patch

Quick fixes feel good.

Understanding the root cause makes you dangerous (in a good way).

A Repeatable Debugging Process

This is where things become practical.

Step 1: Reproduce the Bug

Make it happen consistently.

Click button → error appears  
Refresh → still happens  
Different browser → still happens

If it’s inconsistent, your first task is to find the pattern.

Step 2: Define Expected vs Actual

Write it down clearly.

Expected: API returns user data  
Actual: API returns empty array

This step alone eliminates confusion.

Step 3: Isolate the Problem

Shrink the scope.

Comment out unrelated code
Remove layers (UI → API → DB)
Test pieces independently

Think of it like this:

[ UI ] → [ API ] → [ Database ]

Which layer is lying?

Step 4: Form a Hypothesis

Be explicit:

“I think the API is returning empty data because the query filter is wrong.”

Now you’re not guessing—you’re testing a theory.

Step 5: Test the Hypothesis

Use targeted tools:

Logs
Breakpoints
Network inspector

Example:

console.log("User ID:", userId)

But intentional—not random.

Step 6: Fix and Verify

Fix it.

Then confirm:

Does it work in all cases?
Did you break something else?

Step 7: Understand the Root Cause

This is where most devs stop too early.

Don’t just fix it—explain it:

“The bug happened because the state updated asynchronously, and we read it too early.”

Now you’ve learned something reusable.

Real Example: “The API Is Broken” (But It’s Not)

Let’s walk through a real scenario.

The Bug

Frontend shows: No data available

Initial Assumption

“The API is broken.”

Step 1: Check Network Tab

You open DevTools → Network:

API returns correct data

So… not the API.

Step 2: Check State

console.log(data)

It logs:

[]

Empty array.

Step 3: Trace the Flow

useEffect(() => {
  fetchData()
}, [])

Inside fetchData:

setData(response.data)
console.log(data) // still empty

The Problem

React state updates are asynchronous.

You’re logging before state updates.

The Fix

useEffect(() => {
  fetchData()
}, [])

useEffect(() => {
  console.log(data)
}, [data])

The Lesson

The bug wasn’t in the API.
It was in your mental model of how state updates work.

Tools That Actually Help

Not everything is about tools—but the right ones matter.

1. Browser DevTools (Underrated Powerhouse)

Network tab → verify API calls
Console → inspect runtime values
Application tab → check storage

2. Breakpoints (Game Changer)

Instead of spamming logs:

Pause execution and inspect state live

3. Intentional Logging

Bad:

console.log("here")

Good:

console.log("User after login:", user)

4. Stack Traces

Read them.

They literally tell you:

Where the error happened
What triggered it

5. Rubber Duck Debugging

Explain the bug out loud.

Yes, seriously.

You’ll often solve it mid-explanation.

Problem → Hypothesis → Test → Learn → Repeat

Common Debugging Traps

Avoid these and you’ll already be ahead of most devs:

Fixing Symptoms Instead of Causes

You silence the error… but the bug is still there.

Changing Too Many Things at Once

Now you don’t know what worked.

Ignoring Error Messages

The error is literally telling you what’s wrong.

Read it.

Assuming the Bug Is “Weird”

It’s almost never weird.

It’s misunderstood.

“It Works on My Machine”

This is not a flex.

It’s a clue.

A Better Mental Model

Expectation ≠ Reality  
        ↓  
Investigate the gap

That’s debugging.

Final Thought

The best developers aren’t the ones who write perfect code.
They’re the ones who can quickly understand why things break.

Debugging isn’t a side skill.

It is the job.

Stripe Connect on Accounts v2 — Standard, Express, and Custom, Rebuilt Around Configurations (with HTTP, Python, C#, and PHP)

Billy Okeyo — Mon, 06 Apr 2026 00:00:00 +0000

This is the Accounts v2 companion to the original Connect guide (Accounts v1). Same platform concepts—Standard, Express, Custom, money flow, compliance—but the API shape is the one Stripe describes in Connect and the Accounts v2 API. Use the older post when you must stay on v1 (Account.create with type=express, OAuth-only Standard flows, etc.). Use this post when you are designing around one Account, configurations, and customer_account.

Heads-up: v2 uses different endpoints and JSON than classic Accounts CRUD. Always confirm API version, preview flags, and SDK support in Stripe’s documentation before shipping production code.

What is Stripe Connect?

Stripe Connect is for platforms that move money between buyers, sellers, and your platform. You connect connected accounts to your platform account so you can:

Collect payments from customers
Pay out to sellers or service providers
Take application fees where appropriate

Stripe holds the payments rail; you own product and UX choices.

Two ideas at once: “style” (Standard / Express / Custom) and “shape” (v2 configurations)

The original guide compares Standard, Express, and Custom as who owns onboarding, dashboards, and compliance.

Accounts v2 adds a separate axis: what capabilities a single Account has, expressed as configurations:

Configuration (v2)	Role in plain language
`merchant`	Accept card payments, get paid out—what you usually wanted from aconnected account selling on your platform.
`customer`	Bebilled like a customer (subscriptions, invoices to your platform) using the same Account identity—often replacing a separate Customer object for that business.
`recipient`	Receivetransfers (e.g. indirect charges), using the v2 transfer capabilities Stripe documents for recipients.

You can assign one or more configurations to the same Account. That is the core promise of v2: one identity, multiple roles, less manual ID mapping.

The Standard / Express / Custom choice is still real: it describes OAuth vs Stripe-hosted onboarding vs fully custom UI. On v2 you implement those experiences while creating and updating Accounts through the v2 surface (where supported).

Standard vs Express vs Custom (unchanged product trade-offs)

Feature / aspect	Standard	Express	Custom
Who owns the Stripe relationship	The user’sexisting Stripe user; you connect via OAuth.	You createconnected accounts; Stripe hosts onboarding and a light** dashboard.	You ownall UX; Stripe is invisible to end users.
KYC / onboarding	User usesStripe Dashboard.	Stripe-hosted onboarding (Account Links, etc., per current docs).	You collect data and satisfy Stripe requirements via API.
Dashboard	FullStripe dashboard for the user.	Express dashboard.	None unless you build it.
Best when	Sellersalready have Stripe.	You needspeed and shared compliance.	You needfull branding and control.

On v2, you still make these product choices—but you attach merchant / customer / recipient configurations to match what each connected business must do.

Architectural overview

Fund flow is unchanged at a high level:

flowchart LR
  C[Customer] --> P[Your platform]
  P --> A[Connected Account]
  A --> B[Bank payout]

What changes in v2 is object modeling:

One Account can represent both “seller” and “buyer of your SaaS” if you add merchant and customer configurations.
APIs that took customer may accept customer_account with an Account ID—see using Accounts as customers.

Accounts v2 primitives (before code)

Stripe’s v2 Account objects differ from v1’s flat Account create. You typically send:

identity — country, entity type, business details.
configuration — nested blocks such as merchant, customer, recipient, each with capabilities you request (card_payments, balance / payout capabilities as named in current docs).
defaults — currency, locales, responsibilities (fees / losses collector), etc.
include — ask the API to return nested sections (e.g. configuration.merchant, requirements).

Responses may omit fields unless you include them—see Stripe’s note on includable response values.

API version: v2 calls often require a specific Stripe-Version header (including preview versions while the API evolves). Set this from the exact value in Stripe’s Accounts v2 docs for your integration window.

Implementation: creating an Account on v2 (HTTP-first)

Official examples are REST + JSON. Below is illustrative—copy field names, capability keys, and version from the current docs, not from this blog alone.

cURL (canonical pattern from Stripe)

Stripe documents POST /v2/core/accounts with a JSON body. Conceptually:

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Stripe-Version: <version-from-stripe-docs>" \
  -H "Content-Type: application/json" \
  --data '{
    "contact_email": "seller@example.com",
    "display_name": "Example Seller",
    "identity": {
      "country": "us",
      "entity_type": "company",
      "business_details": { "registered_name": "Example Co" }
    },
    "configuration": {
      "merchant": {
        "capabilities": {
          "card_payments": { "requested": true }
        }
      },
      "customer": {
        "capabilities": {
          "automatic_indirect_tax": { "requested": true }
        }
      }
    },
    "defaults": {
      "currency": "usd",
      "responsibilities": {
        "fees_collector": "stripe",
        "losses_collector": "stripe"
      },
      "locales": ["en-US"]
    },
    "include": [
      "configuration.customer",
      "configuration.merchant",
      "identity",
      "requirements"
    ]
  }'

This shows the mental model: one create, multiple configurations, explicit includes.

Python (generic HTTP client)

Until your stripe SDK exposes stable helpers for every v2 path, httpx or requests keeps you aligned with the docs:

import os
import requests

def create_account_v2():
    r = requests.post(
        "https://api.stripe.com/v2/core/accounts",
        headers={
            "Authorization": f"Bearer {os.environ['STRIPE_SECRET_KEY']}",
            "Stripe-Version": "<version-from-stripe-docs>",
            "Content-Type": "application/json",
        },
        json={
            # ...same structure as the cURL example...
        },
        timeout=30,
    )
    r.raise_for_status()
    return r.json()

PHP (Laravel-style)

Use Guzzle or Laravel Http::withHeaders([...])->post(...) with the same URL, Stripe-Version, and JSON body. Keep secrets in config, not in source control.

C# (.NET)

Use HttpClient with StringContent(json, Encoding.UTF8, "application/json") and the same headers. Deserialize the JSON response into your own DTOs that track id, requirements, and configuration.* state.

OAuth / Standard accounts: Stripe currently directs platforms that authenticate with OAuth to connected accounts to continue using v1 for that path. Treat Standard as documented in the v1 guide until your OAuth + v2 story is explicitly supported for your use case—see Accounts v2 and OAuth.
{: .prompt-tip }

Onboarding links (Express-style flows)

For Express-like experiences you still send users through Stripe-hosted onboarding where the product allows it. With a connected account ID returned from v2 (acct_...), Account Links (v1 resource) remain the usual tool for account_onboarding—the same pattern as the v1 article, but the account value may come from a v2 create. Verify compatibility for your API version in Stripe’s docs.

Python (v1 Account Links API, account id from v2 create):

import stripe
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

link = stripe.AccountLink.create(
    account=connected_account_id,
    refresh_url="https://yourapp.com/reauth",
    return_url="https://yourapp.com/complete",
    type="account_onboarding",
)

Custom-style integrations on v2

Custom still means: you own KYC collection, ToS acceptance, and ongoing verification. On v2 you express that by:

Sending complete identity data the API requires.
Requesting merchant / recipient capabilities your product needs.
Handling requirements and webhooks the same way you would for Custom on v1—only the payload shape differs.

You may still use tos_acceptance-style fields where the v2 schema maps them; follow Stripe’s v2 reference for exact property names.

Using Accounts as customers (`customer_account`)

Where you used customer=cus_..., many flows accept customer_account=acct_... for an Account that has the customer configuration. Example pattern from Stripe (conceptual):

curl https://api.stripe.com/v1/setup_intents \
  -u "sk_test_...:" \
  -H "Stripe-Version: <version-from-stripe-docs>" \
  -d customer_account=acct_123 \
  -d "payment_method_types[]=card" \
  -d confirm=true \
  -d usage=off_session

Details and supported objects live under using Accounts as customers.

Checking balances

For many Connect operations, connected account scoping is unchanged. Python:

balance = stripe.Balance.retrieve(stripe_account=account_id)

PHP:

$balance = \Stripe\Balance::retrieve([], ['stripe_account' => $accountId]);

C#:

var balance = await stripe.Balance.GetAsync(
    new BalanceGetOptions(),
    new RequestOptions { StripeAccount = accountId }
);

Confirm in Stripe’s docs whether your v2 account IDs behave identically for every Balance and v1 helper you rely on during migration.

Compliance responsibilities

The Standard / Express / Custom compliance split from the original article still applies who collects KYC and who owns disputes. v2 can reduce duplicate identity collection when you add configurations to an existing Account instead of opening a second Customer record.

Responsibility	Standard	Express	Custom
KYC	Stripe	Mostly Stripe	You
Tax reporting	Stripe-heavy	Shared	Often you
PCI	Stripe-hosted elements	Shared	Mostly you
Disputes	Stripe-heavy	Shared	Often you

Choosing a path

Scenario	Style to favor	v2 angle
Sellers already on Stripe; OAuth	Standard	Oftenv1 OAuth until Stripe supports your OAuth + v2 plan
Fast marketplace onboarding	Express	v2 `Account` + `merchant` + Account Links
White-label, embedded finance	Custom	v2 full `identity` + capabilities + your UI
Same business pays youand sells on your platform	Express or Custom	Same*`Account`, `merchant`* + `customer` configurations

Strategic considerations

Time-to-market: Standard (when OAuth fits) < Express < Custom.
API surface: v2 adds configuration discipline—plan for migration from v1, not an eternal split (Stripe discourages maintaining both versions simultaneously). - Reference
SDKs: Expect to use HTTP for some v2 paths until your language SDK is fully aligned.

Final thoughts

Accounts v2 does not erase Standard / Express / Custom—it repackages how you represent connected users in the API. Start from Connect and the Accounts v2 API, add using Accounts as customers when the same legal entity both sells and buys from your platform, and keep the v1 Connect guide handy for OAuth flows and legacy snippets until you have fully moved.

Either way, you still trade off control, compliance, and complexity—only the object model got a long-overdue upgrade.

Contract Testing: Prevent Breaking Changes Before Production

Billy Okeyo — Thu, 19 Mar 2026 00:00:00 +0000

“It worked locally. Tests passed. But production still broke.”

If you’re building distributed systems with multiple services and frontends, you’ve likely encountered this (whether using .NET + Angular , Node.js + React , Python + Vue , or any combination):

A backend change gets deployed
The frontend suddenly breaks
No tests warned you

The issue isn’t always logic.

It’s often a broken contract between systems.

The Problem: Silent API Breakages

In a typical setup:

Service Provider: An API or microservice
Service Consumer: A frontend, app, or another service
Communication: JSON over HTTP (or any protocol)

Everything depends on one thing:

The consumer and provider agreeing on what data looks like

A Real Example

Let’s use a .NET API and Angular frontend as an example (though this applies to any tech stack).

API Provider (Initial Version)


public class UserDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
}




[HttpGet("{id}")]
public IActionResult GetUser(int id)
{
    return Ok(new UserDto
    {
        Id = 1,
        Name = "Billy",
        Email = "billy@example.com"
    });
}

Consumer Interface (Angular Example)

export interface User {
  id: number;
  name: string;
  email: string;
}

Everything works perfectly.

Then a “Small” Change Happens

public class UserDto
{
    public int Id { get; set; }
    public string FullName { get; set; } // renamed
    public string Email { get; set; }
}

Production Result

user.name // undefined

The UI breaks.

Why Didn’t Traditional Tests Catch This?

Unit tests → passed (backend logic is fine)
Integration tests → passed (they used the old model)
The API still returns valid JSON

But the contract between systems changed —and traditional tests don’t verify that.

What is Contract Testing?

Contract testing ensures that your service provider always matches what the consumer expects.

A contract defines:

Request format
Response structure
Required fields
Data types

In Simple Terms

The consumer (frontend, app, or service) defines expectations The provider (API or service) must satisfy them

Consumer vs Provider

Consumer

Calls the service/API
Defines expected structure
Examples: Angular frontend, React app, mobile app, another microservice

Provider

Returns the data
Must not break expectations
Examples: .NET API, Node.js backend, Python service, GraphQL endpoint

How Contract Testing Works

Instead of relying only on integration tests:

Angular defines expectations
A contract file is generated
.NET verifies the contract

Flow

Consumer Test (e.g., Angular)
      ↓
Generates Contract
      ↓
Saved as JSON/YAML
      ↓
Provider verifies against contract (e.g., .NET API)

Practical Example

(.NET backend + Angular frontend as an example)

Step 1: Define Expectations in Consumer (Angular example)

const expectedUser = {
  id: 1,
  name: "Billy",
  email: "billy@example.com"
};

it("should fetch user correctly", async () => {
  const user = await userService.getUser(1);
  expect(user).toEqual(expectedUser);
});

Generated Contract (Simplified)

{
  "request": {
    "method": "GET",
    "path": "/api/users/1"
  },
  "response": {
    "body": {
      "id": 1,
      "name": "Billy",
      "email": "billy@example.com"
    }
  }
}

Step 2: Verify in Provider (.NET API example)

Install Pact:

dotnet add package PactNet

Provider Test

[Fact]
public void VerifyPact()
{
    var pactVerifier = new PactVerifier();

    pactVerifier
        .ServiceProvider("UserApi", "http://localhost:5000")
        .WithFileSource(new FileInfo("pacts/userapi-angular.json"))
        .Verify();
}

If Provider Breaks the Contract


1

public string FullName { get; set; }

The test fails immediately
You catch the issue before deployment

Where Contract Testing Fits

E2E Tests
(user journeys)

Integration Tests
(service interactions)

Contract Tests 
(API agreements)

Unit Tests
(business logic)

Why This Matters in Real Projects

Safer Refactoring

Change DTOs, schema, or API responses without fear. Contract tests verify nothing broke.

Independent Development

Consumer and provider teams move faster. Changes are caught instantly, not in production.

Faster Debugging

Failures clearly show what broke

Stronger CI/CD Pipelines

Consumer Build → Generate Contract
Provider Build → Verify Contract
Deploy → Only if both pass

This works with any tech stack.

Common Mistakes

Over-Specifying Data

Bad:

"name": "Billy Okeyo"

Good:

"name": "string"

Testing Everything

Only validate fields your frontend actually uses

Ignoring Versioning

Breaking contracts without versioning leads to production issues

Best Practices

Keep Contracts Minimal

Focus only on required fields

Version Your API

/api/v1/users
/api/v2/users

Automate in CI/CD

Contracts should be generated and verified automatically

Use Realistic Data

Avoid unrealistic mocks

Final Takeaway

Unit tests verify logic Integration tests verify systems E2E tests verify user flows

Contract tests verify agreements

“Most production bugs aren’t failures… they’re misunderstandings between systems.”

Contract testing eliminates those misunderstandings.

Why Your Django App Needs Redis and Celery in Production

Billy Okeyo — Mon, 16 Mar 2026 00:00:00 +0000

Django is an incredibly powerful framework for building web applications quickly. However, as your application grows, certain tasks begin to slow down request-response cycles.

Examples include:

Sending emails
Generating reports
Processing uploaded files
Running background analytics
Sending notifications

Running these tasks during an HTTP request can make your application slow and unreliable.

This is where Celery and Redis come in.

Together they allow you to run background jobs asynchronously without blocking your main application.

The Problem with Synchronous Tasks

Imagine a user submits a request that triggers an operation that takes 10 seconds.

For example:

Generating a financial report
Parsing a large document
Sending multiple emails

If your application processes this synchronously:


1

User Request → Django → Long Task → Response

The user waits for the entire process to finish.

This leads to:

Slow responses
Poor user experience
Possible request timeouts

Introducing Celery

Celery is a distributed task queue that allows you to run background jobs outside the request-response cycle.

Instead of executing tasks immediately, Django sends the job to a queue.

A worker then processes it asynchronously.

The flow becomes:


User Request
    ↓
Django
    ↓
Queue Task
    ↓
Immediate Response
    ↓
Celery Worker
    ↓
Executes Job

This makes your application fast and scalable.

Why Redis?

Celery requires a message broker to manage task queues.

Redis is commonly used because it is:

Extremely fast
Lightweight
Easy to deploy
Perfect for queues and caching

Redis stores the tasks until workers pick them up.

Example: Sending Email in the Background

Instead of sending email directly in a Django view:

send_mail(
    "Welcome",
    "Thanks for signing up",
    "noreply@example.com",
    [user.email],
)

You create a Celery task:

from celery import shared_task
from django.core.mail import send_mail

@shared_task
def send_welcome_email(email):
    send_mail(
        "Welcome",
        "Thanks for signing up",
        "noreply@example.com",
        [email],
    )

Then call it asynchronously:

send_welcome_email.delay(user.email)

The user gets an immediate response while the email is processed in the background.

Common Use Cases for Celery

Celery is useful for many production tasks:

Email sending

Welcome emails
Notifications
Password resets

Data processing

Financial calculations
AI processing
Data pipelines

Scheduled tasks

Daily reports
Cleaning expired sessions
Updating analytics

Running Celery in Production

A typical Django production stack might look like this:

Users
  ↓
Nginx
  ↓
Gunicorn
  ↓
Django App
  ↓
Redis (Broker)
  ↓
Celery Workers

Each component plays a role:

Nginx handles web traffic
Gunicorn runs Django
Redis manages task queues
Celery workers execute background jobs

Scaling Celery Workers

One of Celery’s biggest advantages is scalability.

If tasks increase, you simply add more workers.

celery -A project worker --loglevel=info --concurrency=4

More workers mean faster task processing.

Final Thoughts

Celery and Redis are essential tools for running Django applications at scale.

They allow you to:

Improve response times
Handle heavy workloads
Build scalable architectures
Run background processing reliably

If your Django application handles tasks that take more than a few seconds, moving them to Celery is one of the best architectural decisions you can make.

A Practical Guide to File Uploads (Images, Excel, CSV) in Angular + Django

Billy Okeyo — Mon, 23 Feb 2026 00:00:00 +0000

File uploads are one of those features that look simple… until they aren’t.

Images need previewing. CSV files need parsing. Excel files need validation. Large files need handling. And suddenly your “simple upload” becomes a full feature.

In this guide, we’ll build a practical and production-ready file upload system using:

Angular (Frontend)
Django + Django REST Framework (Backend)

We’ll cover:

Image uploads with preview
CSV uploads and parsing
Excel uploads and processing
Validation and security best practices

Backend Setup (Django + DRF)

1. Install Dependencies

pip install djangorestframework pillow openpyxl pandas

pillow → Image processing
openpyxl → Excel support
pandas → CSV & Excel parsing

2. Configure Media Files

settings.py

MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

urls.py (project level)

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # your urls
]

if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Part 1: Image Upload

Django Model

from django.db import models

class Profile(models.Model):
    name = models.CharField(max_length=100)
    image = models.ImageField(upload_to='profiles/')

Serializer

from rest_framework import serializers
from .models import Profile

class ProfileSerializer(serializers.ModelSerializer):
    class Meta:
        model = Profile
        fields = ' __all__'

View

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.parsers import MultiPartParser, FormParser
from rest_framework import status

class ProfileUploadView(APIView):
    parser_classes = [MultiPartParser, FormParser]

    def post(self, request):
        serializer = ProfileSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

Angular Frontend (Image Upload)

HTML

<input type="file" (change)="onFileSelected($event)" accept="image/*" />
<img *ngIf="previewUrl" [src]="previewUrl" width="200" />
<button (click)="upload()">Upload</button>

Component

selectedFile!: File;
previewUrl: string | ArrayBuffer | null = null;

onFileSelected(event: any) {
  this.selectedFile = event.target.files[0];

  const reader = new FileReader();
  reader.onload = () => {
    this.previewUrl = reader.result;
  };
  reader.readAsDataURL(this.selectedFile);
}

upload() {
  const formData = new FormData();
  formData.append('name', 'Billy');
  formData.append('image', this.selectedFile);

  this.http.post('http://localhost:8000/api/upload/', formData)
    .subscribe(res => console.log(res));
}

Part 2: CSV Upload and Parsing

Django View for CSV

import pandas as pd
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.parsers import MultiPartParser

class CSVUploadView(APIView):
    parser_classes = [MultiPartParser]

    def post(self, request):
        file = request.FILES['file']

        if not file.name.endswith('.csv'):
            return Response({'error': 'Invalid file type'}, status=400)

        df = pd.read_csv(file)

        # Example processing
        total_rows = len(df)
        columns = list(df.columns)

        return Response({
            'rows': total_rows,
            'columns': columns
        })

Angular CSV Upload

uploadCSV(file: File) {
  const formData = new FormData();
  formData.append('file', file);

  this.http.post('http://localhost:8000/api/upload-csv/', formData)
    .subscribe(res => console.log(res));
}

Part 3: Excel Upload (.xlsx)

Django View for Excel

class ExcelUploadView(APIView):
    parser_classes = [MultiPartParser]

    def post(self, request):
        file = request.FILES['file']

        if not file.name.endswith('.xlsx'):
            return Response({'error': 'Invalid file type'}, status=400)

        df = pd.read_excel(file)

        summary = {
            'rows': len(df),
            'columns': list(df.columns)
        }

        return Response(summary)

Validation & Security Best Practices

1. Limit File Size

In settings.py:

DATA_UPLOAD_MAX_MEMORY_SIZE = 5242880 # 5MB

2. Validate File Type Properly

Don’t rely only on extension.

if file.content_type not in ['image/jpeg', 'image/png']:
    return Response({'error': 'Invalid image format'}, status=400)

3. Rename Uploaded Files

import uuid

def upload_to(instance, filename):
    ext = filename.split('.')[-1]
    return f"uploads/{uuid.uuid4()}.{ext}"

4. Handle Large Files with Streaming

For very large CSV files, process in chunks:

for chunk in pd.read_csv(file, chunksize=1000):
    # process chunk
    pass

Bonus: Returning Processed Data

Sometimes you don’t just upload — you process and return a result file.

Example: Generate processed CSV

from django.http import HttpResponse

response = HttpResponse(content_type='text/csv')
response['Content-Disposition'] = 'attachment; filename="processed.csv"'
df.to_csv(response, index=False)
return response

Final Thoughts

File uploads are not just about saving files.

They are about:

Validation
Security
User experience
Scalability

When done correctly, they become powerful data pipelines inside your application.

If you’re building admin systems, reporting tools, learning platforms, or fintech dashboards — mastering uploads is essential.

2025 in Review: A Year of Growth, Resilience, and Practical Engineering

Billy Okeyo — Mon, 29 Dec 2025 00:00:00 +0000

Who would’ve thought I’d open my editor on the 29th of December not to debug production or chase a failing test—but to write this recap? Because apparently, I enjoy explaining bugs to the internet.

If you told me at the beginning of 2025 that I’d spend the year writing about scalable systems, testing strategies, outages, performance optimizations, and developer excuses I would’ve believed you. If you also told me I’d still be debugging things that “worked yesterday,” I would’ve believed you even faster.

This article is a recap of everything I wrote this year: the lessons, the wins, the bugs, and the “how did this even pass code review?” moments. Think of it as a Spotify Wrapped , but for technical articles, minus the judgment (okay, maybe a little).

**System Design & Scalability — Because Your App Will Grow (Whether You’re Ready or Not)**

Summary: This year, I spent a lot of time talking about scalable backend systems — not because every app needs to handle millions of users, but because every app eventually meets its first “why is the server on fire?” moment.

How to Build Scalable Backend Systems with Python, C#, PHP and DartA practical guide to designing systems that won’t collapse the moment your app gets featured on Twitter… or worse, WhatsApp groups.

Key lesson: Scalability isn’t about overengineering — it’s about not regretting your life choices later.

Testing — Trust Issues, But Make Them Automated

Summary: Testing dominated a good part of the year, mainly because nothing builds trust issues faster than code that looks correct but isn’t.

This series walked through testing from the basics to full CI/CD integration — because “it works on my machine” is not a deployment strategy.

Unit, Integration, and End-to-End Tests — Part 1Where we learn that tests are not the enemy — flaky tests are.
Unit Testing in Depth — Part 2Small tests, big confidence.
Integration Testing in Depth — Part 3When components finally talk to each other… and start arguing.
End-to-End Testing in Depth — Part 4Testing your app the same way users break it.
The Testing Pyramid & CI/CD — Part 5The moment you realize automation saves both time and sanity.

Key lesson: Tests don’t slow you down — debugging production issues does.

Performance & Tooling — Making Code Faster Without Sacrificing Sleep

Summary: Performance optimization showed up in different forms this year — from modern runtimes to build optimizations. Because sometimes the app isn’t slow… it’s just doing unnecessary work very enthusiastically.

Diving into WebAssembly: What It Is and Why It MattersFor when JavaScript alone just isn’t fast enough.
Tree Shaking in TypeScriptRemoving code you forgot existed but was still shipped to production.

Key lesson: If users say your app is slow, they’re probably right. The logs just haven’t confessed yet.

Engineering Culture — Because Code Is Written by Humans (Flawed Ones)

Summary: Not everything this year was serious architecture talk. Some articles leaned into the very human side of software development — where excuses are plentiful and accountability is… negotiable.

Top 10 Developer Excuses When Code BreaksA humorous breakdown of things we’ve all said — and what actually went wrong.

Key lesson: If you’ve never blamed the cache, the network, or “some weird edge case,” are you even a developer?

Industry Case Studies — Learning the Hard Way (So You Don’t Have To)

Summary: One of the most impactful pieces this year was breaking down a real-world outage — because nothing teaches engineering humility like watching large systems fail in creative ways.

What Engineers Can Learn From the Cloudflare OutageA reminder that one bad configuration can humble the biggest companies.

Key lesson: Distributed systems don’t fail loudly — they fail politely, globally, and at the worst possible time.

What 2025 Really Taught Me

If I had to summarize the year in engineering truths:

Scalability matters before users complain.
Tests are cheaper than apologies.
Performance issues hide in plain sight.
Systems fail — preparation determines whether you panic or recover.
Developers are predictable creatures with unpredictable bugs.

Looking Ahead

In the next year, expect:

More real-world case studies
Deeper dives into distributed systems and cloud patterns
Practical articles you can actually apply on Monday morning

Thank you for reading, sharing, and occasionally finding bugs in my examples (yes, I see you).

Here’s to another year of writing code, fixing mistakes, and pretending we knew what we were doing all along.

What Engineers Can Learn From the Cloudflare Outage (November 2025)

Billy Okeyo — Fri, 21 Nov 2025 00:00:00 +0000

How a single oversized configuration file brought down parts of the internet and why this matters for every engineering team.

On November 18, 2025, the internet shook a little.

Cloudflare, the massive networking and security platform powering millions of websites globally, experienced a major outage that resulted in widespread 5xx errors across the internet. For several hours, key services like CDN routing, Workers KV, Access authentication, and even Cloudflare’s own dashboard were degraded.

In their official incident report , Cloudflare broke down exactly what happened, and the root cause was surprisingly small and deceptively simple:

A configuration file grew larger than expected, violated a hidden assumption in the proxy code, and triggered runtime panics across the global edge.

This incident is a powerful case study in modern distributed systems. Let’s break down what went wrong — and why engineers everywhere should take note.

What Actually Happened? A Chain Reaction From One Oversized File

The root cause began with a permissions change in Cloudflare’s ClickHouse database cluster , which led to duplicate rows in a dataset used by their Bot Management engine. That duplication caused the generated “feature file”, a config-like file that proxies rely on to double in size.

Here’s where assumptions came back to haunt them:

Cloudflare’s proxy engine expected a maximum of 200 features.
The new file exceeded that limit.
An .unwrap() in their Rust-based FL2 proxy assumed the file would always be valid.
That assumption failed — the code panicked — resulting in cascading 5xx failures.

As Cloudflare noted in their report, this caused two types of breakage across their edge:

FL2 proxies (new engine): Panicked → produced 5xx errors
FL proxies (old engine): Failed to process bot scores → defaulted to zero → broke logic in Access, rules, authentication, and security products

To make things even more confusing, Cloudflare’s status page (hosted externally) briefly went offline too, creating a misleading early hypothesis that the outage was a massive DDoS attack.

It wasn’t. It was configuration drift.

Why This Seemingly Small Bug Became a Big Internet Event

Config files have become “just another part of the deployment pipeline,” especially in cloud platforms where machine-generated metadata drives features. But Cloudflare’s outage shows:

Config is not static
Config can be corrupted
Config needs validation just like code

Because this file was distributed globally across tens of thousands of Cloudflare servers, a single flawed generation step caused a worldwide issue within minutes.

Distributed systems amplify mistakes — both good ones and bad ones.

Key Engineering Lessons We Should All Learn

1. Never rely on hidden assumptions

Cloudflare’s proxy code assumed the feature file would never exceed a certain size. That “should never happen” moment is often the birthplace of outages.

Lesson: Add explicit limits, schema checks, and sanity validations to all config ingestion paths.

2. Configuration is part of your software supply chain

The feature file was generated, replicated, and consumed automatically — no human intervention. That makes it just as risky as code.

Lesson: Treat configuration pipelines as first-class citizens: test them, validate them, gate them.

3. Build for graceful degradation, not hard crashes

A single .unwrap() took down parts of the internet.

Lesson: Fail softly. If config is invalid, degrade safely, skip rules, or revert to defaults — don’t panic.

4. Feature flags and kill switches are essential

Cloudflare themselves acknowledged the need for a more robust kill-switch system in their follow-up plans.

Lesson: Every modern engineering team should have:

global feature kill switches
fast configuration rollback
manual override options

5. Monitoring needs context, not just alarms

Many engineers watching the outage thought it was an external attack. Alerting didn’t tell them where the failure was coming from, just that everything was “down.”

Lesson: Monitoring should distinguish between:

origin failure
edge failure
config failure
auth failure
internal propagation issues

Context reduces misdiagnosis.

6. Observability tools must be lightweight during crises

During recovery, Cloudflare reported that their debugging systems started consuming high CPU, which slowed other mission-critical services.

Lesson: Your troubleshooting tools must use minimal resources when the system is stressed.

7. Transparency helps the whole industry learn

Cloudflare’s detailed post-mortem is a model for engineering culture. Their openness helps engineers worldwide understand real failure modes in large-scale systems.

Lesson: Share your failures. They help others avoid the same mistakes.

The Bigger Picture: Why This Incident Matters

Cloudflare’s outage wasn’t just a story about a config file. It was a reminder of how fragile the modern internet can be:

We automate everything
We trust our pipelines
We deploy continuously
We assume schemas won’t change
We rely on millions of machines making the same decision correctly

But when the assumptions underneath those systems break, failures propagate at machine speed.

For engineers, SREs, DevOps teams, and platform architects, this incident underscores a fundamental truth:

Your system is only as resilient as your least-validated assumption.

Final Thoughts

Cloudflare’s outage was a blip in the timeline of the internet, but the lessons are timeless.

Distributed systems will always fail, the question is how gracefully they fail, how quickly they recover, and how deeply the organization learns from the event.

Cloudflare’s transparency, analysis, and remediation steps set a strong example for engineering teams everywhere.

Stripe Connect Integration Guide — Standard, Express, and Custom Accounts Explained (with Laravel, C#, and Python Examples)

Billy Okeyo — Tue, 21 Oct 2025 00:00:00 +0000

Update (2026): Stripe’s Accounts v2 API uses a unified Account with configurations (merchant, customer, recipient) so one identity can sell, pay your platform, and receive transfers without parallel Customer IDs. For a full guide in the same spirit as this article—but aligned to v2—see Stripe Connect on Accounts v2. Everything below remains the reference for Accounts v1 (Account.create, OAuth, Account Links as shown). V2 though is the recommended path for the new Stripe Connect Integrations.
{: .prompt-tip }

Stripe offers a powerful ecosystem for building payment platforms, marketplaces, and financial applications.
One of its most powerful products, Stripe Connect, allows you to facilitate payments between multiple parties while maintaining flexibility over branding, compliance, and user experience.

Choosing between Standard, Express, and Custom accounts is one of the most important architectural decisions you’ll make when designing a payment platform.
This guide combines a step-by-step tutorial and deep technical analysis to help you understand and implement each type.

What Is Stripe Connect?

Stripe Connect is designed for platforms that process payments on behalf of others.
It enables you to connect user accounts (called Connected Accounts) to your Platform Account so you can:

Collect payments from customers
Distribute payouts to vendors, lenders, or service providers
Optionally collect platform fees

Your platform never needs to hold funds directly (unless you design it to), and Stripe handles the movement of money under the hood.

Connected Accounts Overview

Each connected account represents a business, seller, or user on your platform.
Depending on how much control and responsibility you want, you’ll choose between:

Standard — Stripe handles almost everything.
Express — Stripe handles compliance, you handle limited UX.
Custom — You handle everything; Stripe is invisible to your users.

Feature / Aspect	Standard	Express	Custom
Ownership of Stripe Account	User owns and manages their Stripe account directly.	User gets a lightweight managed account. Stripe handles UI for onboarding and dashboards.	Full control; your platform owns the payment experience. Users never see Stripe.
KYC / Onboarding	Handled entirely by Stripe via the user’s Stripe dashboard.	Stripe-hosted onboarding flow with minimal setup.	You collect all KYC data through your own UI and pass it to Stripe’s API.
Dashboard Access	User uses Stripe’s own dashboard.	Limited dashboard (Stripe Express Dashboard).	No dashboard; your app must display balances, transactions, etc.
Compliance Responsibility	Stripe handles everything.	Stripe handles most KYC and compliance.	You are responsible for collecting and transmitting KYC data.
Control over UI/UX	Minimal; users leave your app to manage payments.	Moderate; Stripe provides branded but embeddable flows.	Full; completely white-labeled experience.
Ideal Use Case	Marketplaces where users already have Stripe accounts.	Platforms needing simple onboarding (e.g., gig apps).	Fintech, lending, or platforms needing deep financial workflows.

Architectural Overview

All three integration types share a common flow:

Customer → Your Platform → Connected Account → Bank Payout

However, the control points differ:

With Standard, Stripe owns the UX and dashboard.
With Express, Stripe hosts onboarding and dashboard, but your platform manages relationships.
With Custom, your platform builds everything: UI, onboarding, payouts, and reporting.

Step-by-Step Implementation by Account Type

Let’s look at how to implement each account type with C#, Laravel (PHP) and Python examples and understand their implications.

Standard Accounts — Easiest Setup, Minimal Control

Concept

Standard accounts are the simplest to integrate.
Users connect their own existing Stripe accounts using OAuth. Stripe handles compliance, payouts, and reporting. Your platform receives a small application fee from each transaction.

Use Case

Ideal for marketplaces or SaaS platforms where users already have Stripe accounts and prefer to manage their own dashboards.
{: .prompt-tip }

Implementation

C

var accountLink = await stripe.AccountLinks.CreateAsync(new AccountLinkCreateOptions {
    Account = connectedAccountId,
    RefreshUrl = "https://your-platform.com/reauth",
    ReturnUrl = "https://your-platform.com/success",
    Type = "account_onboarding",
});

Laravel (PHP)

$accountLink = \Stripe\AccountLink::create([
    'account' => $connectedAccountId,
    'refresh_url' => route('stripe.reauth'),
    'return_url' => route('stripe.success'),
    'type' => 'account_onboarding',
]);

Python

import stripe
stripe.api_key = "sk_test_..."

account_link = stripe.AccountLink.create(
    account=connected_account_id,
    refresh_url="https://your-platform.com/reauth",
    return_url="https://your-platform.com/success",
    type="account_onboarding"
)

Pros and Cons

Pros

Minimal setup
Stripe handles everything (KYC, compliance, payouts)
Reduced liability

Cons

Limited branding control
Users must leave your platform to manage payments
Harder to create a unified experience

Express Accounts — Fast Onboarding, Shared Control

Concept

Express accounts strike a balance between simplicity and control.
You manage account creation and linking, but Stripe handles onboarding and provides a lightweight dashboard for your users.

Use Case

Perfect for gig or service platforms (like driver or freelancer apps) where quick onboarding and basic payout visibility are key.
{: .prompt-tip }

Implementation

C

var account = await stripe.Accounts.CreateAsync(new AccountCreateOptions {
    Type = "express",
    Country = "US",
    Email = "user@example.com"
});

var link = await stripe.AccountLinks.CreateAsync(new AccountLinkCreateOptions {
    Account = account.Id,
    RefreshUrl = "https://yourapp.com/reauth",
    ReturnUrl = "https://yourapp.com/complete",
    Type = "account_onboarding"
});

Laravel (PHP)

$account = \Stripe\Account::create([
    'type' => 'express',
    'country' => 'US',
    'email' => $request->input('email'),
]);

$link = \Stripe\AccountLink::create([
    'account' => $account->id,
    'refresh_url' => route('stripe.reauth'),
    'return_url' => route('stripe.success'),
    'type' => 'account_onboarding',
]);

Python

account = stripe.Account.create(
    type="express",
    country="US",
    email="user@example.com"
)

link = stripe.AccountLink.create(
    account=account.id,
    refresh_url="https://yourapp.com/reauth",
    return_url="https://yourapp.com/complete",
    type="account_onboarding"
)

Pros and Cons

Pros

Faster onboarding
Stripe handles compliance and verification
Users get access to payout history via the Express dashboard

Cons

Limited customization
Stripe branding remains visible
Less flexibility over reporting or custom payout logic

Custom Accounts — Full Control, Full Responsibility

Concept

Custom accounts are designed for white-labeled platforms.
Your app controls everything: onboarding, KYC collection, balances, and payouts.
Stripe is completely invisible to the end user.

Use Case

Ideal for fintech, embedded finance, lending, or any system that requires deep integration and custom user experiences.
{: .prompt-tip }

Implementation

C

var accountOptions = new AccountCreateOptions {
    Type = "custom",
    Country = "US",
    Email = data.Email.ToLower(),
    Capabilities = new AccountCapabilitiesOptions {
        CardPayments = new AccountCapabilitiesCardPaymentsOptions { Requested = true },
        Transfers = new AccountCapabilitiesTransfersOptions { Requested = true }
    },
    TosAcceptance = new AccountTosAcceptanceOptions {
        Date = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
        Ip = httpContext.Connection.RemoteIpAddress.ToString()
    }
};

var account = await stripe.Accounts.CreateAsync(accountOptions);

Laravel (PHP)

$account = \Stripe\Account::create([
    'type' => 'custom',
    'country' => 'US',
    'email' => strtolower($data['email']),
    'capabilities' => [
        'card_payments' => ['requested' => true],
        'transfers' => ['requested' => true],
    ],
    'tos_acceptance' => [
        'date' => time(),
        'ip' => request()->ip(),
    ],
]);

Python

account = stripe.Account.create(
    type="custom",
    country="US",
    email=data["email"].lower(),
    capabilities={
        "card_payments": {"requested": True},
        "transfers": {"requested": True},
    },
    tos_acceptance={
        "date": int(time.time()),
        "ip": request.remote_addr,
    }
)

Fund Flow Example

+--------------------------------------+
|             Platform (You)           |
|    No direct money handling          |
+--------------------+-----------------+
                     |
                     ▼
          Create & Manage Connected Accounts
                     |
   +--------------------------------------+
   |     Connected Account (Business)     |
   |  💵 Has Stripe balance, bank info    |
   |  🧾 Disburses and collects funds     |
   +--------------------------------------+

Money Movement

IN: Customer → Connected Account (via ACH/Card)
OUT: Connected Account → Bank (payouts)
Platform orchestrates, Stripe moves the money

Checking Balances

Python

balance = stripe.Balance.retrieve(stripe_account=account_id)

Laravel (PHP)

$balance = \Stripe\Balance::retrieve([], ['stripe_account' => $accountId]);

C

var balance = await stripe.Balance.GetAsync(
    new BalanceGetOptions(),
    new RequestOptions { StripeAccount = accountId }
);

Compliance Responsibilities

Responsibility	Standard	Express	Custom
KYC	Stripe	Stripe	You
Tax Reporting	Stripe	Stripe	You
PCI Compliance	Stripe-hosted	Shared	Mostly you
Dispute Handling	Stripe	Shared	You
Branding	Stripe	Partial	Fully yours

Tip: For Custom accounts, implement Stripe Identity, webhooks, and Stripe Radar to automate verification and fraud detection.
{: .prompt-tip }

Choosing the Right Integration Type

Scenario	Recommended Type
Marketplace with existing Stripe users	Standard
Platform needing fast onboarding	Express
Fintech, lending, or white-labeled finance	Custom

Strategic Considerations

Time-to-market: Standard < Express < Custom
Compliance load: Stripe-heavy → Custom-heavy
Branding control: Minimal → Full
Revenue potential: Low (Standard) → High (Custom)

Final Thoughts

Every Stripe Connect integration represents a trade-off between control, compliance, and complexity:

Standard — easiest to deploy, lowest control
Express — balanced control and simplicity
Custom — ultimate flexibility with greater responsibility

If your goal is speed, start with Express.
If your goal is brand control and scalability, build with Custom.

Either way, Stripe Connect gives you a future-proof foundation for managing payments, onboarding users, and creating rich financial experiences all through powerful APIs available across languages.

The Testing Pyramid: Wrapping Up with CI/CD and Best Practices - Part 5

Billy Okeyo — Fri, 19 Sep 2025 00:00:00 +0000

Software testing is more than writing a few unit tests and hoping for the best. To deliver reliable software, teams need a balanced testing strategy — one that combines Unit, Integration, and End-to-End (E2E) tests in the right proportions. This is where the Testing Pyramid comes in.

In this final part of our testing series, we’ll:

Understand the Testing Pyramid model.
Explore how to balance different types of tests.
Learn how to integrate testing into CI/CD pipelines.
Review best practices for building a sustainable testing culture.

The Testing Pyramid Explained

The Testing Pyramid (popularized by Mike Cohn) is a metaphor for structuring automated tests:



        ▲
        | End-to-End (fewest, slowest)
        |
        | Integration (moderate amount, balanced)
        |
        | Unit Tests (largest base, fastest)
        ▼

1. Unit Tests (Foundation)

Fast, cheap, and precise.
Cover small pieces of logic in isolation.
Should make up 60–70% of your automated test suite.

Example: Testing a function that calculates interest rates.

2. Integration Tests (Middle Layer)

Validate how components interact.
Cover database queries, API requests, or service orchestration.
Should make up 20–30% of your test suite.

Example: Ensuring your API endpoint correctly fetches data from the database and formats the response.

3. End-to-End Tests (Top)

Simulate real user flows across the full stack.
Catch bugs unit or integration tests can’t.
Should make up 10–15% of your suite (because they’re slow and expensive).

Example: A test where a user logs in, adds a product to their cart, and completes checkout.

Integrating Tests into CI/CD Pipelines

Automated tests are only valuable if they’re run consistently. Modern software teams embed them into CI/CD pipelines.

Step 1: Run Unit Tests Early

Execute on every commit or pull request.
Fail fast: block merges if unit tests fail.

Step 2: Run Integration Tests on Build/Deploy

Run after the app compiles successfully.
Can use a containerized test environment with mock or staging databases.

Step 3: Run End-to-End Tests on Staging

Triggered before production deployment.
Some teams run smoke E2E tests in production (carefully) to ensure critical flows still work.

Example CI/CD Flow (GitHub Actions / GitLab / Jenkins):

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install dependencies
        run: npm install
      - name: Run unit tests
        run: npm test -- --unit
      - name: Run integration tests
        run: npm test -- --integration
      - name: Run e2e tests
        run: npm run test:e2e

Best Practices for a Balanced Testing Strategy

1. Follow the Pyramid, Not the Ice Cream Cone

Too many E2E tests = slow, brittle pipeline.
Too few unit tests = shaky foundation.
Balance is key.

2. Use Test Doubles Wisely

Mocks/Stubs in unit tests to isolate dependencies.
Minimal mocking in integration tests — rely on real services where possible.

3. Make Tests Deterministic

Tests should always produce the same result.
Avoid flaky tests (caused by race conditions, timeouts, or external dependencies).

4. Keep Tests Fast

Aim for seconds, not minutes.
Developers won’t run slow tests locally.

5. Automate Everything in CI/CD

Manual testing has its place, but regression checks must be automated.
CI/CD pipelines should be your safety net before production.

6. Monitor and Improve Test Coverage

Coverage isn’t everything, but low coverage usually indicates gaps.
Focus on critical paths rather than chasing 100%.

7. Treat Tests as Code

Tests should be maintainable, reviewed, and refactored like production code.
Avoid “test rot” where tests become outdated or ignored.

Final Thoughts

The journey from unit → integration → E2E tests gives you confidence at every level of your system.

Unit tests keep your building blocks solid.
Integration tests ensure the blocks fit together.
E2E tests confirm the entire structure works as intended.

By following the Testing Pyramid , integrating tests into CI/CD pipelines , and practicing discipline in writing effective tests, you’ll achieve:

Faster feedback loops.
Fewer production bugs.
Higher developer confidence.
Happier end-users.

Testing isn’t just about catching bugs, it’s about building trustworthy software at scale.

Next Steps for You:

Audit your current test suite.
See if you’re over-relying on one type of test.
Gradually reshape your suite into a pyramid , not an ice cream cone.

End-to-End (E2E) Testing in Depth - Part 4

Billy Okeyo — Fri, 12 Sep 2025 00:00:00 +0000

If unit tests check individual functions, and integration tests check how those functions work together, end-to-end (E2E) tests take it all the way: They simulate real user workflows from start to finish, ensuring the entire application stack works as expected.

E2E testing is about validating the system as a whole , covering everything from frontend to backend, database, APIs, and sometimes even external services.

What Are E2E Tests?

E2E tests replicate user behavior and verify that the system responds correctly. Think of them as automated users interacting with your app.

Example workflows tested in E2E:

User logs in → Dashboard loads correctly.
User creates a record → It’s stored in DB → Appears in the UI.
Checkout flow in an e-commerce app → Product added → Payment processed → Order confirmed.

Why E2E Tests Matter

Validate Real Workflows → Ensure the system behaves like users expect.
Catch System-Wide Failures → Config issues, routing errors, DB schema mismatches.
Test Critical Paths → Login, payments, onboarding, search, etc.
Provide Business Confidence → Stakeholders see features working as intended.

Characteristics of E2E Tests

High Coverage – Test across the full stack.
Slowest of All Tests – Often run in CI/CD pipelines, not during active coding.
Brittle – Small UI changes can break tests, so balance is key.
Mimic Real User Behavior – Often browser-driven or API-driven.

Side-by-Side Examples

Scenario:

A user visits a web app, logs in, and sees their profile page with their name.

Python (Selenium + pytest)

# test_e2e_login.py
from selenium import webdriver
from selenium.webdriver.common.by import By
import pytest

@pytest.fixture
def driver():
    driver = webdriver.Chrome()
    yield driver
    driver.quit()

def test_login_flow(driver):
    driver.get("http://localhost:5000/login")

    driver.find_element(By.NAME, "username").send_keys("alice")
    driver.find_element(By.NAME, "password").send_keys("password123")
    driver.find_element(By.ID, "login-button").click()

    profile_name = driver.find_element(By.ID, "profile-name").text
    assert profile_name == "Alice"

C# (Selenium + xUnit)

using Xunit;
using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;

public class LoginE2ETests
{
    [Fact]
    public void Login_ShowsProfilePage()
    {
        using var driver = new ChromeDriver();
        driver.Navigate().GoToUrl("http://localhost:5000/login");

        driver.FindElement(By.Name("username")).SendKeys("alice");
        driver.FindElement(By.Name("password")).SendKeys("password123");
        driver.FindElement(By.Id("login-button")).Click();

        var profileName = driver.FindElement(By.Id("profile-name")).Text;
        Assert.Equal("Alice", profileName);
    }
}

TypeScript (Playwright / Cypress)

(Playwright example below — Cypress would be very similar)

// login.e2e.test.ts
import { test, expect } from "@playwright/test";

test("user can login and see profile page", async ({ page }) => {
  await page.goto("http://localhost:3000/login");

  await page.fill("input[name=username]", "alice");
  await page.fill("input[name=password]", "password123");
  await page.click("#login-button");

  const profileName = await page.textContent("#profile-name");
  expect(profileName).toBe("Alice");
});

PHP (Laravel Dusk for browser automation)

// tests/Browser/LoginTest.php
<?php

namespace Tests\Browser;

use Laravel\Dusk\Browser;
use Tests\DuskTestCase;

class LoginTest extends DuskTestCase
{
    public function testUserCanLoginAndSeeProfile()
    {
        $this->browse(function (Browser $browser) {
            $browser->visit('/login')
                    ->type('username', 'alice')
                    ->type('password', 'password123')
                    ->press('Login')
                    ->assertSee('Alice');
        });
    }
}

Comparison Table

Aspect	E2E Testing Goal	Python (Selenium)	C# (Selenium + xUnit)	TypeScript (Playwright/Cypress)	PHP (Laravel Dusk)
Scope	Full user workflow (UI → backend → DB)	✅	✅	✅	✅
Tools	Selenium	Selenium	Playwright/Cypress	Dusk (browser automation)
Speed	Slow (browser interaction)	Slow	Medium	Medium/Fast
Confidence	Highest — validates the system end-to-end	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐
Best For	Login flows, payments, user journeys	UI + API flows	UI + API flows	Fullstack web apps	Laravel apps

Best Practices for Writing Effective E2E Tests

Test Critical User Journeys Only
- Focus on login, checkout, payments, onboarding, etc.
- Don’t waste time E2E testing every small feature.
Keep Tests Deterministic
- Avoid flakiness by controlling test data.
- Seed databases with known test records.
Use Test-Specific Environments
- Run E2E tests in staging or CI environments.
- Isolate from production data and services.
Clean Up After Tests
- Ensure created records (users, orders) are rolled back or deleted.
Use IDs and Stable Selectors
- Avoid brittle selectors like div:nth-child(3).
- Use unique IDs or data-test attributes.
Parallelize and Optimize
- Run tests in parallel (e.g., Playwright, Cypress).
- Keep them minimal to avoid bloated CI runs.
Combine with Unit & Integration Tests
- Don’t rely solely on E2E.
- Use a test pyramid strategy:
Monitor and Review Regularly
- E2E tests can get brittle.
- Review and refactor when the UI or workflows change.

Key Takeaways

E2E tests replicate the user’s journey and validate the full system.
They are slower and more brittle , but they give the highest level of confidence.
Use them sparingly for critical paths (login, payments, core workflows).
Balance your test pyramid:
Choose the right tools for your stack (Selenium, Playwright, Cypress, Dusk).
Follow best practices to keep tests reliable and maintainable.

Integration Testing in Depth : Test components working together (and not hate it) Part 3

Billy Okeyo — Fri, 05 Sep 2025 00:00:00 +0000

Integration tests sit in the sweet spot between tiny, fast unit tests and slow, expensive end-to-end tests. They verify that multiple parts of your system cooperate correctly e.g., your API layer talks to the DB the way you expect, background jobs persist state, or your service correctly handles responses from an external API.

This post is a practical, language-agnostic guide to integration testing, plus side-by-side, runnable patterns for Python , C# (.NET), TypeScript (Node/Express) and PHP (Laravel) so you can immediately apply the ideas in your stack.

What integration tests are (and are not)

Integration tests verify behavior across component boundaries, multiple classes, modules, services or infrastructure pieces that would not be exercised by a unit test.

They are not:

A replacement for unit tests (they’re slower & coarser).
Full UI-driven E2E tests (unless you intentionally include the UI).

They are good for:

Verifying DB reads/writes via your data access layer.
Testing service-to-service interactions.
Ensuring message queue jobs and workers together produce expected state.
Checking how your app handles external API payloads (with a mock or stub of that API).

Goals & tradeoffs

Goals

Catch bugs that only appear when components are wired together.
Validate API contracts inside your own system.
Give more realistic coverage than unit tests.

Tradeoffs

Slower than unit tests.
Harder to make fully deterministic (external services, timing).
Need careful setup/teardown to stay reliable.

Core patterns & recommendations

1. Use realistic but controlled dependencies

Prefer a real database (or the same engine, e.g., PostgreSQL) rather than mocking DB calls.
For external services (payment gateways, email providers), use service doubles : a local mock server, WireMock, or HTTP interceptors (nock, responses, Http::fake). Don’t call the live service in CI.

2. Isolate tests

Run each test in a transaction and roll it back (if possible), or recreate schema between tests.
Or give each test its own ephemeral database (unique DB name/per-worker) when running tests in parallel.

3. Keep tests focused

Each integration test should exercise a meaningful interaction or flow (e.g., API -> DB, or API -> external-service-stub -> DB), not every possible path.

4. Seed deterministic test data

Use builders/fixtures to create known state. Avoid random data unless seeded.

5. Manage long-running processes

For queues/workers, either run workers synchronously in tests, use a fake queue, or spin up a test worker process in CI.

6. Use testcontainers or docker-compose in CI

For close-to-production fidelity, use Testcontainers (or docker-compose) to provision real DBs and services in CI.

7. Avoid flaky tests

No sleeps/time-based races. Use blocking signals, polling with timeouts, or deterministic stubs.

When to mock vs when to use real services

Real DB : Prefer real DB engine (Postgres, MySQL). SQLite is OK for many cases but can mask engine-specific issues.
External APIs : Mock in integration tests. Use contract testing (Pact) to keep mocked expectations in-sync.
Caches/Queues : Use in-memory or test doubles unless you must validate the actual middleware behavior.

Observability: make debugging failing integration tests easy

Emit structured logs during tests (include request IDs).
Capture and print responses and DB state on failure.
Keep helpful assertion messages.

Checklist: test lifecycle

Create test environment (DB, migrations applied).
Seed minimal deterministic data.
Execute action via real interfaces (HTTP client, direct call).
Assert state persisted, side effects happened (e.g., DB row created, message pushed, HTTP call stubbed).
Tear down (transaction rollback, truncate tables, drop DB).

Common pitfalls & fixes

Flaky tests : avoid sleep-based waiting; use retry-with-timeout polling and assert deterministically.
Slow setup : keep per-test setup minimal; use transactional rollback where possible.
Parallel test collisions : give tests separate DBs or use unique table prefixes.
“Works locally but fails in CI” : mirror CI environment locally using Docker/Testcontainers and run tests there.

Example integration tests (side-by-side)

Scenario used across examples:

A POST /users endpoint that creates a user record in the database and triggers an HTTP call to an external email service (welcome email). Integration test will create a user via HTTP, verify DB row exists, and verify the email call was made (mocked).

Python — FastAPI + SQLAlchemy + pytest + requests-mock

Notes: Use sqlite:///:memory: or a Testcontainers Postgres for higher fidelity in CI. requests-mock stubs outgoing HTTP calls.

# app.py (pseudo)
from fastapi import FastAPI, Depends
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

app = FastAPI()

# App factory to pass different DB URLs in tests
def create_app(db_url, email_service_url):
    engine = create_engine(db_url)
    Session = sessionmaker(bind=engine)
    # create tables...
    app.state.db = Session
    app.state.email_url = email_service_url

    @app.post("/users")
    def create_user(payload: dict):
        sess = app.state.db()
        user = User(name=payload["name"], email=payload["email"])
        sess.add(user); sess.commit()
        # Send welcome email via requests.post(app.state.email_url, json=...)
        return {"id": user.id}

    return app


# test_integration.py
import pytest
from fastapi.testclient import TestClient
import requests_mock
from app import create_app

@pytest.fixture
def client(tmp_path):
    # Use sqlite in-memory for speed or file DB for persistence across app
    app = create_app("sqlite:///:memory:", "http://email.test/send")
    client = TestClient(app)
    yield client

def test_create_user_and_send_email(client):
    with requests_mock.Mocker() as m:
        m.post("http://email.test/send", status_code=200, json={"ok": True})
        resp = client.post("/users", json={"name":"Alice","email":"a@example.com"})
        assert resp.status_code == 200
        user_id = resp.json()["id"]

        # Verify DB row exists (open a session)
        Session = client.app.state.db
        sess = Session()
        user = sess.query(User).filter_by(id=user_id).one_or_none()
        assert user is not None
        assert user.email == "a@example.com"

        # Verify external email call occurred
        assert m.called
        assert m.request_history[0].json() == {"to": "a@example.com", "template": "welcome"}

Tips

For CI, replace sqlite with Testcontainers Postgres: create_app(postgres_url, ...).
Use DB migrations in setup if using a real DB.

C# (.NET) — ASP.NET Core + WebApplicationFactory + InMemory DB / Testcontainer

Notes: Use WebApplicationFactory<TEntryPoint> to spin the app in tests and override service registrations for test doubles.

// In Startup.cs, app reads EmailService via IEmailService (HttpEmailService in prod)

public class TestEmailService : IEmailService {
    public List<EmailMessage> Sent = new();
    public Task SendAsync(EmailMessage msg) { Sent.Add(msg); return Task.CompletedTask; }
}

// Integration test
public class UsersIntegrationTests : IClassFixture<WebApplicationFactory<Program>> {
    private readonly WebApplicationFactory<Program> _factory;

    public UsersIntegrationTests(WebApplicationFactory<Program> factory) {
        _factory = factory.WithWebHostBuilder(builder => {
            builder.ConfigureServices(services => {
                // Replace real DB with in-memory or Testcontainer; replace email service with TestEmailService
                services.AddSingleton<IEmailService, TestEmailService>();
                // Configure EF Core to use InMemoryDatabase or connection string from Testcontainers
            });
        });
    }

    [Fact]
    public async Task PostUsers_CreatesUser_And_SendsEmail() {
        var client = _factory.CreateClient();
        var content = new StringContent("{\"name\":\"Bob\",\"email\":\"b@ex.com\"}", Encoding.UTF8, "application/json");
        var resp = await client.PostAsync("/users", content);
        resp.EnsureSuccessStatusCode();

        // Verify DB: use scope to resolve DbContext
        using(var scope = _factory.Services.CreateScope()) {
            var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
            var user = db.Users.Single(u => u.Email == "b@ex.com");
            Assert.NotNull(user);
        }

        // Verify TestEmailService captured message
        var emailService = _factory.Services.GetRequiredService<IEmailService>() as TestEmailService;
        Assert.Single(emailService.Sent);
        Assert.Equal("welcome", emailService.Sent[0].Template);
    }
}

Tips

For a real DB in CI, use Testcontainers .NET to spin up Postgres and set EF Core connection string.
Overriding services avoids brittle HTTP stubbing, and keeps assertions in-process.

TypeScript (Node/Express) — supertest + sqlite in-memory + nock

Notes: supertest issues HTTP requests to your Express app instance. Use nock to intercept outgoing HTTP.

// app.ts (pseudo)
import express from "express";
import bodyParser from "body-parser";
import { initDb } from "./db";

export function createApp(dbPath: string) {
  const app = express();
  app.use(bodyParser.json());
  const db = initDb(dbPath); // e.g., sqlite3 in-memory or file
  app.post("/users", async (req, res) => {
    const { name, email } = req.body;
    const id = await db.run("INSERT INTO users(name,email) VALUES(?,?)", [name, email]);
    // call external email service via fetch/http client
    await fetch("http://email.test/send", { method: "POST", body: JSON.stringify({ to: email, template: "welcome" }) });
    res.json({ id });
  });
  return app;
}


// test/integration.test.ts
import request from "supertest";
import nock from "nock";
import { createApp } from "../app";
import { openDb, getUserById } from "../db";

describe("POST /users", () => {
  it("creates a user and calls email service", async () => {
    const app = createApp(":memory:");
    const email = nock("http://email.test")
      .post("/send", (body) => body.to === "c@ex.com" && body.template === "welcome")
      .reply(200, { ok: true });

    const res = await request(app)
      .post("/users")
      .send({ name: "Carol", email: "c@ex.com" })
      .expect(200);

    // verify DB
    const user = await getUserById(res.body.id);
    expect(user.email).toBe("c@ex.com");

    // verify external call was made
    expect(email.isDone()).toBe(true);
  });
});

Tips

For complex schemas, use migrations in test setup or run a dedicated test DB with sqlite file per test.
For Postgres in CI, spin up DB via docker-compose or Testcontainers Node.

PHP (Laravel) — HTTP tests + RefreshDatabase + Http::fake()

Notes: Laravel has excellent integration testing helpers. RefreshDatabase runs migrations and transacts where possible. Use Http::fake() to intercept external HTTP.

// routes/api.php
Route::post('/users', [UserController::class, 'store']);

// UserController->store uses User model and Http::post('http://email.test/send', ...);


// tests/Feature/CreateUserTest.php
<?php
namespace Tests\Feature;

use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Http;
use Tests\TestCase;
use App\Models\User;

class CreateUserTest extends TestCase
{
    use RefreshDatabase;

    public function test_create_user_and_send_welcome_email()
    {
        Http::fake([
            'email.test/*' => Http::response(['ok' => true], 200),
        ]);

        $response = $this->postJson('/api/users', [
            'name' => 'Dan',
            'email' => 'd@ex.com',
        ]);

        $response->assertStatus(200);

        // verify DB
        $this->assertDatabaseHas('users', ['email' => 'd@ex.com']);

        // assert that an outbound call was made
        Http::assertSent(function ($request) {
            return $request->url() == 'http://email.test/send' &&
                   $request['to'] == 'd@ex.com' &&
                   $request['template'] == 'welcome';
        });
    }
}

Tips

Laravel’s RefreshDatabase will use in-memory sqlite if configured, otherwise migrate a test DB.
Use Queue::fake() to test that jobs were dispatched without executing background workers.

Practical integration testing strategies

Use transactions for isolation

Wrap each test in a DB transaction and roll back at the end. Works well when everything runs in the same DB connection.
Caveat: some ORMs/connections (e.g., tests that spawn separate processes) might not share transaction visibility.

Use in-memory DBs for speed, but test on real DBs in CI

SQLite in-memory is fast, but can behave differently (indexing, SQL dialect). Complement local tests with real-engine tests in CI using containers.

Stubbing external HTTP reliably

Python: responses or requests-mock
Node: nock
C#: WireMock.Net or replace typed HttpClient with test handler
PHP: Laravel Http::fake()

Testcontainers — real dependencies in CI

Spin up a Postgres, Redis, or Kafka container for integration tests.
Testcontainers exists for many ecosystems (Java, .NET, Node, Python wrappers).

Contract testing for cross-team APIs

Use Pact or similar to generate contracts from consumer tests and verify provider compliance in provider CI. This avoids brittle mocks and catches breaking API changes.

Background jobs & queues

Either run job handlers inline (synchronously) in tests, use fake queues that record enqueued messages, or run a worker process in CI that reads from test queue.

How many integration tests should you write?

No fixed number. Aim for:

Unit tests: many (business logic)
Integration tests: enough to cover critical integration points (DB persistence, payment flows, auth)
E2E tests: few (critical user paths)

A practical rule: write integration tests for each major DB operation and for the essential external integrations.

Debugging failing integration tests

Print request/response bodies and DB rows on failure.
Capture network traffic (or enable higher logging).
Reproduce the failing test locally with the same CI container setup (Testcontainers makes that easy).
If a test is flaky, add instrumentation and increase visibility; temporary retries mask real issues.

Sample integration test checklist

Before merging an integration test into CI:

Test uses deterministic data.
DB schema/migrations run and are applied in setup.
External dependencies are stubbed or provided by test containers.
Test cleans up (transaction rollback or truncation).
No sleeps or time-based races.
Test is focused on behavior, not implementation.

Wrapping up & next steps

Integration tests reduce the mismatch between isolated units and the full system. They give higher confidence than unit tests while being cheaper and faster than full E2E tests. When designed well they catch boundary problems early and make refactoring safer.

Next post in the series: End-to-End (E2E) Testing in Depth — we’ll cover realistic end-to-end strategies, UI-driving vs API-only E2E, test environments, flaky UI tests, and how to design low-maintenance high-value E2E checks.

Happy testing!