Your signup page works. The dashboard loads. Checkout completes in test mode. That can feel like enough evidence to launch.
Then a real customer signs in with an expired session. Another receives access after a failed payment. A duplicate webhook creates two billing records. An authorization check protects the interface but not the underlying Server Action. Everything looked correct during development because every test followed the same successful path the developer expected.
A production-ready SaaS testing strategy is not about maximizing the number of test files. It is about proving that the parts capable of harming customers, exposing data, blocking revenue, or corrupting state behave correctly under both expected and hostile conditions.
For a Next.js and Supabase SaaS, that normally means combining fast Vitest tests, direct database and Row Level Security tests, integration tests around server boundaries, billing and webhook simulations, and a small set of Playwright journeys covering the flows customers depend on most.
The purpose of testing is not to prove that the code can work. It is to discover the conditions under which it will not.
What Is the Best Testing Strategy for a Next.js SaaS?
The best Next.js SaaS testing strategy is a risk-based system with several complementary layers:
| Testing layer | Primary responsibility | Typical tools | What it should catch |
|---|---|---|---|
| Static quality gates | Invalid types, unsafe imports, lint violations and build failures | TypeScript, ESLint, Next.js build | Problems that can be detected without executing a customer workflow |
| Unit tests | Isolated business rules and state transitions | Vitest | Incorrect calculations, validation, branching and formatting |
| Integration and contract tests | Communication between application boundaries | Vitest, test databases, provider fixtures | Incorrect persistence, malformed provider payloads and partial mutations |
| Database security tests | Schema behavior, constraints, functions, grants and RLS | Supabase CLI, pgTAP | Cross-user access, missing constraints and authorization bypasses |
| End-to-end tests | Critical user-visible journeys | Playwright | Broken routing, sessions, forms, browser behavior and system integration |
| Production verification | Safe confirmation after deployment | Health checks, smoke tests, monitoring | Environment-specific configuration and deployment regressions |
Next.js distinguishes between unit, component, integration and end-to-end testing. Its current documentation also recommends end-to-end testing for asynchronous Server Components because unit-testing support for them remains limited in the React testing ecosystem. That is an important architectural constraint: not every Next.js behavior belongs in Vitest. Some behavior can only be trusted after the application has been built and exercised through a browser. See the official Next.js testing guide and Next.js Vitest guide.
No individual layer can replace the others. A successful Playwright checkout cannot prove that a duplicated webhook is idempotent. A passing unit test cannot prove that a user is blocked by Supabase RLS. A pgTAP policy test cannot prove that a browser correctly handles an expired session.
The layers should overlap around risk, not duplicate every implementation detail.
Test by Customer Risk, Not by File Count
A common testing mistake is to create one test for every utility, component or source file. This produces activity and coverage numbers, but it does not necessarily protect the product.
A better model starts with the failures that would create the most damage.
| Risk area | Possible customer impact | Testing priority |
|---|---|---|
| Authentication and authorization | Account takeover, private data exposure or unauthorized actions | Critical |
| Billing and entitlements | Free access, paid customers locked out, incorrect refunds or revenue leakage | Critical |
| Database migrations and RLS | Data loss, broken deployment or cross-user access | Critical |
| Webhooks and background jobs | Delayed state, duplicate processing or permanently lost work | High |
| Account and profile workflows | Incorrect customer records or blocked account management | High |
| Marketing components | Cosmetic regressions or reduced conversion | Medium |
| Internal formatting helpers | Minor display inconsistency | Low unless used in financial or security-sensitive output |
This approach changes how the test suite grows. A small subscription state machine may deserve more tests than an entire landing page because a wrong result can change customer access. A short authorization helper may deserve positive and negative tests for every role because the consequences of failure are severe.
The broader Next.js SaaS production checklist covers the full release surface. Testing should convert its highest-risk release requirements into repeatable evidence.
What Should You Unit Test With Vitest?
Vitest is most valuable when it tests deterministic business behavior quickly and without requiring a browser, live Supabase project or real payment provider.
Good unit-test candidates include:
- Billing-state and entitlement decisions
- Input validation, normalization and permission rules
- Retry scheduling, usage calculations and analytics formulas
Avoid spending most of the unit-test budget checking whether a visual component renders static text. Prioritize logic where several inputs can lead to materially different outcomes.
Consider a simplified entitlement rule:
export type BillingState =
| "trialing"
| "active"
| "past_due"
| "canceled"
| "unpaid";
type EntitlementInput = {
state: BillingState;
trialEndsAt: Date | null;
accessEndsAt: Date | null;
now: Date;
};
export function hasProductAccess({
state,
trialEndsAt,
accessEndsAt,
now,
}: EntitlementInput): boolean {
if (state === "active") {
return true;
}
if (state === "trialing") {
return trialEndsAt !== null && trialEndsAt > now;
}
if (state === "canceled") {
return accessEndsAt !== null && accessEndsAt > now;
}
return false;
}
The useful tests are not limited to one active and one canceled customer:
import { describe, expect, it } from "vitest";
import { hasProductAccess } from "./has-product-access";
const now = new Date("2026-08-05T12:00:00.000Z");
describe("hasProductAccess", () => {
it("allows an active subscription", () => {
expect(
hasProductAccess({
state: "active",
trialEndsAt: null,
accessEndsAt: null,
now,
}),
).toBe(true);
});
it("rejects an expired trial", () => {
expect(
hasProductAccess({
state: "trialing",
trialEndsAt: new Date("2026-08-05T11:59:59.000Z"),
accessEndsAt: null,
now,
}),
).toBe(false);
});
it("preserves access until the end of a canceled billing period", () => {
expect(
hasProductAccess({
state: "canceled",
trialEndsAt: null,
accessEndsAt: new Date("2026-09-01T00:00:00.000Z"),
now,
}),
).toBe(true);
});
it("does not grant access for an unpaid subscription", () => {
expect(
hasProductAccess({
state: "unpaid",
trialEndsAt: null,
accessEndsAt: null,
now,
}),
).toBe(false);
});
});
These tests document the intended product behavior while protecting the rule from future billing changes.
Vitest provides spies, function mocks and module-mocking utilities through vi. Those tools are useful at genuine system boundaries, but excessive mocking can make a test prove only that its mocks agree with one another. Prefer real domain objects and pure functions. Mock the clock, network client, email sender or provider SDK when necessary—not every internal function.
Does Code Coverage Prove That a SaaS Is Tested?
Code coverage measures which code executed during the tests. It does not establish that the right assertions were made.
A webhook handler can reach 100% line coverage without testing duplicate delivery. An authorization function can have complete branch coverage without attempting access as the wrong user. A billing calculator can execute every line while asserting an incorrect expected value.
Use coverage to discover unexamined code, especially high-risk modules. Do not use one global percentage as the definition of release readiness.
Vitest supports V8 and Istanbul coverage providers. Its coverage configuration can also include source files that were never imported during the test run, which helps expose important modules hidden by deceptively high coverage percentages. See the official Vitest coverage guide.
A useful policy is to require meaningful coverage for security, billing and state-transition modules while treating whole-repository coverage as a diagnostic indicator rather than a business goal.
Test Server Actions and Route Handlers as Public Endpoints
A Server Action may be called from a button inside an authenticated dashboard, but its location in the interface does not authorize it.
The same applies to Route Handlers. An attacker does not need to follow the intended page flow. They can call the server boundary directly with a modified payload, expired session or resource identifier belonging to another customer.
Next.js explicitly recommends treating Server Actions and Route Handlers with the same security considerations as public-facing API endpoints. Authentication and authorization must be checked inside the operation rather than inferred from the page that exposed it.
For each sensitive operation, test the full decision boundary:
| Scenario | Expected result |
|---|---|
| No valid session | Request is rejected before reading or mutating protected state |
| Authenticated but wrong role | Operation returns an authorization failure |
| Correct role but wrong resource owner | Operation cannot access or modify the resource |
| Invalid payload | Validation fails without a partial database mutation |
| Duplicate request | The result remains idempotent or returns a controlled conflict |
| Dependency failure | The operation produces a safe error and preserves recoverable state |
| Valid request | Mutation succeeds and returns only the required data |
A practical architecture keeps the framework wrapper small and moves application behavior into a testable service:
type UpdateProfileDependencies = {
loadProfileOwner: (profileId: string) => Promise<string | null>;
saveDisplayName: (
profileId: string,
displayName: string,
) => Promise<void>;
};
type UpdateProfileInput = {
actorId: string;
profileId: string;
displayName: string;
};
export async function updateProfile(
input: UpdateProfileInput,
dependencies: UpdateProfileDependencies,
): Promise<void> {
const ownerId = await dependencies.loadProfileOwner(input.profileId);
if (ownerId === null) {
throw new Error("PROFILE_NOT_FOUND");
}
if (ownerId !== input.actorId) {
throw new Error("FORBIDDEN");
}
const displayName = input.displayName.trim();
if (displayName.length < 2 || displayName.length > 60) {
throw new Error("INVALID_DISPLAY_NAME");
}
await dependencies.saveDisplayName(input.profileId, displayName);
}
The Server Action can verify the session, parse untrusted input and call this service. Vitest can then exercise ownership, validation and persistence behavior without launching a browser.
The browser test still matters, but it should confirm that the visible workflow is connected correctly—not become the only proof that authorization exists.
Test Supabase RLS as a Security Boundary
Application-level permission tests are not enough when Supabase Row Level Security protects the data.
A route test might prove that one handler checks ownership. It does not prove that another query, an incorrectly configured client or a future feature cannot read the same row. RLS tests verify the database’s own answer to the question: “Can this identity perform this operation on this record?”
Supabase recommends automated database tests for schema behavior, functions, constraints and RLS policies. Its local testing workflow uses pgTAP through supabase test db, allowing database tests to run transactionally and roll back after execution. The documentation also emphasizes negative authorization cases and isolated test data for application-level tests. See the Supabase testing overview and testing and linting guide.
A policy test should prove what another user cannot do, not only what the owner can do.
begin;
select plan(2);
insert into auth.users (id, email)
values
('11111111-1111-1111-1111-111111111111', 'owner@example.com'),
('22222222-2222-2222-2222-222222222222', 'other@example.com');
insert into public.projects (id, owner_id, name)
values (
'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
'11111111-1111-1111-1111-111111111111',
'Private project'
);
set local role authenticated;
select set_config(
'request.jwt.claims',
'{"sub":"11111111-1111-1111-1111-111111111111","role":"authenticated"}',
true
);
select results_eq(
$$
select count(*)::bigint
from public.projects
where id = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
$$,
array[1::bigint],
'owner can read the project'
);
select set_config(
'request.jwt.claims',
'{"sub":"22222222-2222-2222-2222-222222222222","role":"authenticated"}',
true
);
select results_eq(
$$
select count(*)::bigint
from public.projects
where id = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
$$,
array[0::bigint],
'another user cannot read the project'
);
select * from finish();
rollback;
The exact setup will depend on your schema, grants and policy helpers, but the test intent should remain explicit.
For each protected table, verify read, create, update and delete behavior where applicable. Include anonymous access, authenticated access, ownership changes, missing JWT claims and privileged server operations. The complete Supabase RLS guide for Next.js SaaS explains why policies, grants and service-role boundaries need to be reviewed together.
Supabase describes RLS policies as rules that effectively add access conditions to database queries. It also warns that auth.uid() returns null for unauthenticated requests and recommends explicit role and authentication conditions where appropriate.
How Should You Test SaaS Billing and Webhooks?
A payment provider’s sandbox proves that the provider can generate a test transaction. It does not prove that your application will translate every provider event into correct, durable customer access.
Billing tests should cover three connected systems:
| System | Question the tests must answer |
|---|---|
| Provider-facing handler | Is the event authentic, supported and parsed correctly? |
| Local billing state | Is the event stored and processed once without losing history? |
| Product entitlement layer | Does the customer receive or lose the correct access? |
The successful checkout path is only one scenario. Production billing must also survive duplicated events, delayed delivery, unexpected ordering, missing local records, refunds, payment failures and provider retries.
Stripe states that webhook events can be retried automatically, may arrive out of order and should not be processed under the assumption of guaranteed sequencing. Its documentation also provides manual resend mechanisms for failed deliveries. Those behaviors make idempotency and reconciliation test requirements rather than optional hardening.
A meaningful webhook test matrix looks like this:
| Test scenario | Evidence required |
|---|---|
| Valid signed event | Event is accepted and persisted |
| Invalid signature | Handler rejects the request without changing state |
| Same event delivered twice | Only one business transition occurs |
| Events arrive out of order | Final state is derived safely instead of trusting arrival order |
| Customer or subscription is unknown | Event is retained for investigation or reconciliation |
| Processing fails after persistence | Work can be retried without losing the original payload |
| Refund or dispute occurs | Access and financial records follow the defined business policy |
| Handler receives an already processed event | It returns a successful no-op response |
| Provider API is unavailable | State remains recoverable and the failure is observable |
Use provider tooling where it adds evidence. The Stripe CLI can forward sandbox events to a local endpoint and trigger specific event fixtures. Stripe test clocks and billing simulations can move test subscriptions through renewals, trials, upgrades and payment failures without waiting for real calendar time.
Provider simulations should be paired with local contract fixtures. Store representative event payloads for the API versions your application supports, then test parsing and state transitions deterministically in CI.
This is also why billing logic should not be spread across the webhook handler, page loaders and UI components. A central entitlement layer is easier to test and safer to migrate. The SaaS billing architecture guide covers the relationship between provider events, local billing records, reconciliation and product access.
Test Background Jobs Without Waiting for the Background
Transactional email, analytics rollups, billing reconciliation, cleanup tasks and provider synchronization often execute outside the original request.
Testing only the route that enqueues the work leaves the most failure-prone half of the workflow unverified.
Separate the tests into two responsibilities. The request-level test should prove that the correct job or outbox record was created exactly once. The worker test should prove that the stored work can be claimed, executed, retried and completed safely.
For an email workflow, the unit or integration test should not send a real message:
it("queues one verification email for a new account", async () => {
await registerAccount({
email: "founder@example.com",
requestId: "request-123",
});
const messages = await testDatabase.notificationOutbox.findMany({
requestId: "request-123",
});
expect(messages).toHaveLength(1);
expect(messages[0]).toMatchObject({
template: "verify-account",
recipient: "founder@example.com",
status: "pending",
});
});
The worker suite can then cover provider success, temporary failure, permanent rejection, retry backoff, expired leases and duplicate claims. A separate provider contract test can verify that the generated request matches the provider’s expected schema.
This division keeps tests fast without pretending the asynchronous part does not exist. The Next.js background jobs, queues, cron and retries guide provides a deeper model for idempotency, leases, replay and dead-letter handling.
Which User Journeys Belong in Playwright?
Playwright should cover the small number of journeys where browser behavior and multiple systems must work together.
It should not reproduce every unit-test branch through the interface. Large E2E suites become slow, expensive and difficult to debug. When every test creates accounts, waits for providers and depends on shared state, failures become noisy enough that teams begin ignoring them.
Playwright recommends testing user-visible behavior, keeping tests isolated and avoiding dependence on implementation details. Its guidance also recommends using traces to diagnose CI failures rather than recording heavy trace data for every successful test.
For a SaaS product, the first Playwright suite should usually protect journeys like these:
| Journey | What the test proves |
|---|---|
| New account signup and authentication | Forms, redirects, session creation and protected routes work together |
| Existing user sign-in | Session restoration and dashboard access function correctly |
| Checkout or purchase handoff | The customer can reach the configured provider with the correct product |
| Entitled feature access | Paid or authorized users can use the feature while unauthorized users cannot |
| Account settings update | Server Action, validation, persistence and refreshed UI are connected |
| Admin customer investigation | Authorized operators can find a customer while ordinary users remain blocked |
| Cancellation or access-expiry flow | Product access reflects the intended billing state |
The most critical flow should be tested against a production-like build, not only the development server.
Playwright projects can separate fast smoke coverage from broader suites. For example, pull requests might run Chromium smoke tests for authentication, dashboard access and one billing-safe journey. The main branch can run additional browsers and operator workflows. A scheduled suite can cover slower lifecycle scenarios.
Reusing Authentication Safely
Playwright can reuse authenticated browser state to reduce repeated login work. This can make a suite significantly faster, but the saved state may contain sensitive cookies and headers capable of impersonating the test account.
The official authentication guidance recommends storing this state in a dedicated directory and excluding it from version control. Use low-privilege test identities and separate storage states for ordinary users and administrators.
Do not let every test share mutable records merely because it shares an authenticated session. Authentication reuse and test-data isolation are separate concerns.
Build Reproducible Test Data
A test suite becomes unreliable when its outcome depends on whatever records happen to exist in a shared development project.
A stable SaaS test environment needs a known schema, deterministic baseline data and isolated records for each test. Supabase seed files run after migrations during local resets, allowing developers and CI to recreate a consistent environment. Supabase recommends keeping seed files focused on data rather than schema changes.
Use three rules:
- Seed the baseline, generate the scenario. Seed stable plans, feature definitions and configuration. Generate unique customers, subscriptions and resources inside the tests.
- Give every test ownership of its records. Use unique identifiers or namespaces so parallel tests cannot overwrite one another.
- Never use production customer data as casual test data. Build representative fixtures without copying personal information, credentials or live provider identifiers.
A local reset should be capable of applying every migration and producing a usable test state from the repository alone. If the environment requires undocumented dashboard changes before tests pass, it is not reproducible.
What Should Run in CI?
A useful CI pipeline provides feedback in increasing order of cost. Fast deterministic failures should stop the pipeline before browsers and external simulations consume more resources.
A practical sequence is:
pnpm lint
pnpm typecheck
pnpm test:unit
supabase db reset
supabase db lint
supabase test db
pnpm test:contracts
pnpm build
pnpm test:e2e:smoke
The exact commands will vary, but the ordering matters. There is little value in launching Playwright when TypeScript does not compile or a migration cannot recreate the database.
The Supabase CLI supports local database resets, database linting and pgTAP execution. Supabase also documents running database tests in CI after starting the local stack.
Different events can trigger different depths:
| Trigger | Recommended checks |
|---|---|
| Every pull request | Lint, type checking, unit tests, database tests, contracts, build and critical smoke tests |
| Merge to the primary branch | Pull-request suite plus broader integration and E2E coverage |
| Scheduled run | Cross-browser journeys, provider simulations and slower lifecycle tests |
| Before production migration | Migration replay, RLS and grants tests, backfill verification and rollback or forward-fix plan |
| Immediately after deployment | Read-only health checks and safe production smoke verification |
Retries should not be used to make a consistently flaky test appear healthy. A retry can collect diagnostic evidence and distinguish intermittent infrastructure problems, but the original failure still deserves investigation.
Define Release Gates With Evidence
“Tests passed” is too broad to guide a release decision. A release gate should name the risk, the evidence and the consequence of failure.
| Release gate | Evidence | Blocks release? |
|---|---|---|
| Repository quality | Lint, type checking and production build pass | Yes |
| Database reproducibility | All migrations replay from a clean local state | Yes |
| Authorization | Positive and negative Server Action, Route Handler and RLS tests pass | Yes |
| Billing correctness | Signature, duplicate, ordering and entitlement tests pass | Yes |
| Critical journeys | Authentication and primary product smoke tests pass | Yes |
| Provider contracts | Supported webhook fixtures parse successfully | Yes |
| Non-critical browser coverage | Secondary UI and cross-browser suites pass | Depends on affected area |
| Coverage movement | High-risk modules remain adequately exercised | Review rather than automatic global block |
This model prevents a high aggregate pass count from hiding a failure in the one test that protects customer data.
It also makes the test suite easier to maintain. When a test no longer supports a defined risk or release decision, it should be reconsidered rather than preserved only because it already exists.
Common SaaS Testing Mistakes
Testing Only the Happy Path
The happy path proves that the product works when the customer, database, network and payment provider all behave exactly as expected.
Production failures usually appear at the boundaries: an expired session, repeated request, partial provider outage, malformed payload, missing record or unauthorized resource identifier. For every high-risk successful case, write at least one failure case and one permission case.
Mocking the System Into Agreement
A test can mock the database result, provider response, authorization helper and persistence function until there is no real behavior left to verify.
Mocks should isolate unstable external boundaries. They should not replace the contracts between every internal module. Use real validation schemas, real domain functions and representative provider fixtures wherever practical.
Making Playwright Responsible for Everything
An E2E test can detect that checkout is broken. It may not explain whether the problem came from the browser, routing, provider configuration, webhook processing, local billing state or entitlements.
Keep detailed business cases in faster lower layers. Let Playwright prove that the critical pieces are connected.
Chasing 100% Coverage
Perfect coverage can encourage low-value tests while making refactoring expensive. It also creates a false sense of security around behavior the assertions never evaluated.
Prioritize mutation consequences, authorization boundaries, financial calculations and failure recovery. A lower coverage percentage with strong risk coverage is more valuable than a perfect number built from shallow assertions.
Letting Tests Share Mutable State
A suite that passes sequentially but fails in parallel usually has hidden dependencies. Tests may reuse the same email address, account, project, subscription or billing event.
Assign unique data to each scenario. Keep cleanup scoped to records owned by that test. Never rely on test execution order.
A Practical Adoption Plan for an Existing SaaS
You do not need to stop product development and build a perfect testing platform at once.
| Phase | Focus | Deliverable |
|---|---|---|
| First | Protect the highest-risk rules | Unit tests for entitlements, permissions, validation and retry behavior |
| Second | Protect data and integrations | RLS tests, migration replay, webhook contracts and duplicate-event tests |
| Third | Protect customer journeys | Focused Playwright smoke coverage and CI release gates |
| Ongoing | Improve from evidence | Convert escaped production bugs and near misses into durable regression tests |
Start with the failure that would be hardest to explain to a customer.
For most SaaS products, that means unauthorized data access, incorrect billing access, account lockout or a migration that cannot be safely deployed. Once those risks have evidence, expand toward reliability, usability and broader browser coverage.
Frequently Asked Questions
How many tests does a SaaS need before launch?
There is no universal minimum. A SaaS is ready when its highest-impact risks have repeatable evidence. A smaller product may launch with dozens of carefully selected tests, while a mature billing platform may need thousands. Count protected behaviors and failure modes rather than test files.
Should I use Vitest or Playwright for Next.js?
Use both for different responsibilities. Vitest is suitable for fast business rules, validation, service behavior and controlled integrations. Playwright is suitable for critical browser journeys and asynchronous Next.js behavior that requires a built application. Do not force every behavior into one tool.
Do I need pgTAP when I already test my Supabase queries with Vitest?
Application tests and pgTAP answer different questions. Vitest can prove that your application sends the expected query. pgTAP can prove that the database’s policies, functions, constraints and grants permit or reject the operation correctly. RLS should be tested at the database boundary.
Should Playwright tests run against production?
Most E2E tests should run against isolated local, preview or staging environments where mutations are safe. Production verification should be limited to carefully designed read-only checks or controlled synthetic accounts. Never let a normal test suite create purchases, delete customer records or alter real production data.
Is 100% code coverage a good release requirement?
Usually not as a global requirement. Coverage is useful for locating untested code, but it cannot judge assertion quality or business risk. Set stronger expectations for high-risk modules and review coverage movement instead of optimizing the entire repository for one percentage.
Can AI generate the test suite for a SaaS?
AI can accelerate test scaffolding, fixtures and missing-case discovery, but generated tests still need human review. An AI-generated assertion may reproduce the implementation’s mistake or mock away the behavior that matters. The test must be checked against the intended product and security policy, not only the existing code.
Test the Product You Are Actually Shipping
A SaaS test strategy should mirror the product’s real architecture.
If access depends on Supabase RLS, test RLS. If billing depends on webhooks, test duplicates and ordering. If email depends on an outbox worker, test enqueueing and retries. If the customer depends on an asynchronous Next.js page, test the built journey in a browser.
The objective is not a test suite that looks impressive in a repository. It is a release process that gives you defensible answers:
- Can one customer access another customer’s data?
- Can payment events produce incorrect or duplicate access?
- Can a clean environment reproduce the database?
- Can a customer complete the journey that generates value?
When those answers are backed by automated evidence, testing stops being a final launch chore. It becomes part of the SaaS architecture.
Shipflash provides a structured Next.js and Supabase foundation with testing, billing, authentication and operational boundaries designed to be understood and extended. It does not remove the need to test your product-specific behavior, but it gives that behavior a clearer and more maintainable place to live.