How to Write Integration Tests for a Multi-Tenant SaaS App
Your unit tests are green. Your code review is approved. You deploy — and Tenant B can suddenly read Tenant A's invoices. It happens. And when it does, no unit test ever warned you.
Multi-tenancy is one of those architectural decisions that looks clean on a whiteboard but generates an entire class of bugs that only show up when two real tenants interact with shared infrastructure. Integration tests are your last reliable defence before production. This guide shows you exactly how to build them.
Why Unit Tests Are Not Enough
Unit tests mock the database. They mock the ORM. They mock the service layer. That's precisely the problem — they mock away the exact layer where tenant isolation actually breaks.
Isolation bugs almost always live at the boundary between your application logic and the data layer:
- A missing
WHERE tenant_id = ?clause in a query - A background job that pulls all records instead of scoping by tenant
- A shared cache key that collides across tenants
- A soft-delete filter that gets bypassed by a raw query
None of these surface in unit tests. All of them surface in integration tests — if your integration tests are written correctly.
Structuring Your Test Database for Multi-Tenancy
One Schema Per Tenant vs. Shared Schema
How you model tenancy determines how you test it. There are two dominant patterns:
- Shared schema — all tenants share the same tables, distinguished by a
tenant_idcolumn. - Schema-per-tenant — each tenant gets a dedicated database schema (e.g., PostgreSQL schemas).
For shared-schema apps, your integration tests must always operate with at least two active tenants simultaneously. Testing with one tenant tells you nothing about isolation. Testing with two tells you everything.
For schema-per-tenant apps, tests should validate that operations run inside the correct schema context and that there is no cross-schema data leakage via shared sequences or functions.
Seeding: The Foundation of Reliable Tests
Bad seeding is the root cause of most false-positive integration tests. A test that only seeds data for one tenant and then asserts "only one record was returned" proves nothing — there was never competing data to leak.
A solid seed strategy for multi-tenant tests:
async function seedTwoTenants() {
const tenantA = await createTenant({ name: "Acme Corp" });
const tenantB = await createTenant({ name: "Globex Ltd" });
await createRecord({ tenantId: tenantA.id, label: "Invoice #001" });
await createRecord({ tenantId: tenantB.id, label: "Invoice #002" });
return { tenantA, tenantB };
}
Every test that touches a resource endpoint should seed data for at least two tenants and explicitly assert that the requesting tenant only receives its own records. The second tenant's data is the control group — it should never appear in the response.
Writing the Isolation Assertion
This is the assertion most teams forget to write. They assert that the response contains the right records. They never assert that it excludes the wrong ones.
Structure every isolation test in three parts:
- Seed — create overlapping data for two or more tenants.
- Act — make the request authenticated as Tenant A.
- Assert both directions — confirm Tenant A's data is present and Tenant B's data is absent.
Response should contain: Invoice #001
Response should NOT contain: Invoice #002
That second assertion is the one that catches the bug. Without it, you are only testing that your app works — not that it is safe.
Tenant Scoping in Test Setup
Every integration test that touches the API should be authenticated. Do not skip auth in integration tests — the auth layer is often where tenant context is first established, and bypassing it creates a false test environment.
A clean pattern is to create a per-test HTTP client factory that embeds the tenant context:
- Generate a real JWT or session token for the seeded tenant
- Attach it to every request in the test
- Never share a client instance between tests for different tenants
If you use a test framework like Jest, Vitest, or pytest, use beforeEach / afterEach hooks to scope client creation and teardown — not beforeAll. Shared state across tests is how cross-tenant contamination silently enters your test suite.
Teardown: Cleaning Up Without Leaving Ghosts
Incomplete teardown is a silent killer. Leftover tenant data from one test can pollute assertions in another, especially when tests run in parallel.
Two reliable teardown strategies:
- Transaction rollback — wrap each test in a database transaction and roll it back after the test. Fast and clean, but only works if your ORM and test framework support it cleanly.
- Truncation with explicit tenant IDs — after each test, delete all records associated with the seeded tenant IDs. Slower, but works across any stack.
Avoid relying on unique emails or random IDs alone to prevent collisions. Use explicit cleanup. What you do not clean up today becomes the flaky test you spend three hours debugging next sprint.
Testing Background Jobs and Async Processes
Background jobs are a common source of tenant bleed. A job that processes "all pending invoices" without scoping by tenant will cross boundaries silently.
For these, your integration tests should:
- Seed pending records for two tenants
- Trigger the job (either directly or via a test queue)
- Assert that only the correct tenant's records were processed and updated
- Assert that the other tenant's records remain in their original state
This is often overlooked because teams assume background jobs are "internal" — but they touch the same database your API does, under less scrutiny.
Practical Test Organisation
Keep your multi-tenant isolation tests in a dedicated directory or test suite — something like tests/integration/isolation/. This makes them easy to run as a focused gate in CI, separate from your functional integration tests. Your pipeline can fail fast on isolation regressions before running the broader test suite.
Tag or annotate these tests so engineers know their purpose. An isolation test that reads like a functional test will get "fixed" by the next developer who does not understand why it checks for absent data.
Why This Matters for Your Project
If you are building or scaling a SaaS product, tenant isolation is not a feature — it is a contractual obligation to every customer on your platform. A single data leak can trigger GDPR notifications, customer churn, and reputational damage that no hotfix can fully repair. Investing in a rigorous integration test layer for tenant scoping is not engineering overhead — it is the minimum viable trust infrastructure your platform runs on. Build it once, run it on every pull request, and sleep better on every deploy.
