Test the repository directly when the question is about persistence behavior. A rendered-component test can prove that a screen reacts to a result, but it usually cannot tell you whether the repository selected the right collection, preserved an identifier, handled a missing document, or translated a storage failure consistently. Keep a smaller set of UI tests for the user journey; put the data contract in its own focused suite.
This is especially useful in a Next.js SaaS where a data layer is shared by routes, server actions, and background work. Frontend Accelerator’s current product repository exposes a common database adapter and chooses a Firestore or MongoDB implementation behind that boundary. That makes the boundary a useful place to define behavior without claiming that one adapter automatically makes every implementation interchangeable.
What a repository contract test should prove
A contract is the behavior callers are allowed to rely on. It is not a copy of a Firestore SDK call. Start with the smallest set of observable promises a feature needs: find one record, list records, create a record, update a record, and delete a record. For each promise, decide what happens when the record is absent, a write is rejected, or a value needs mapping before it is stored.
The current Firestore adapter in the product repository is a concrete example of why this matters. It exposes generic entity operations, maps document data back to an object with an id, and converts date-shaped values while reading and writing. A route should not need to know which Firestore calls make those things happen. Your contract test should instead assert the outcome a caller receives.
Recommendation: specify behavior in the vocabulary of your domain or repository, then let Firestore remain an implementation detail inside that boundary.
Separate repository behavior from rules behavior
There are two valuable but different test targets. A repository contract test asks whether your server-side persistence boundary behaves as your application expects. A Firestore Security Rules test asks whether a client identity is permitted to perform a client-side request. Do not let a passing test in one category stand in for the other.
Firebase documents that server client libraries bypass Cloud Firestore Security Rules and authenticate through application credentials. That means an Admin-SDK-backed repository suite is not evidence that client access is denied correctly. For rules, use the Emulator Suite and a client-oriented rules test with authenticated and unauthenticated contexts. For repository behavior, use the narrowest safe harness that can exercise your mapping, error handling, and fixture isolation.
Repository contract diagram
Feature or server action
| calls
v
Repository contract
- findById
- list
- create
- update
- delete
| implemented by
v
Firestore adapter ---- local emulator or controlled test double
|
v
Document data, ids, timestamps, failuresThe useful boundary is the repository contract, not a pretend universal database API. If a Firestore behavior is intentionally exposed—for example, an ordered cursor or a transaction—name it explicitly in the contract and test that behavior directly. Hiding a meaningful capability behind an overly generic method only moves the coupling somewhere harder to see.
Build the fixture matrix before the test code
Write the expected states first. It keeps the suite from becoming a set of screenshots of today’s implementation and gives you a clear reason for each fixture.
Fixture: one known document
Seed a record with a stable id and representative fields. Assert that a read returns the domain shape you promised, including the id and any intentionally normalized date value. Do not assert every internal Firestore representation unless it is part of the public repository result.
Fixture: an empty collection
Assert the list behavior you want: usually an empty array, not a special UI-shaped value. This is a small test with a large payoff because it keeps “no results” handling consistent across server actions and pages.
Fixture: a missing document
Ask for an id that is not present and assert the selected contract: null, a typed result, or a domain-specific not-found error. Pick one and document it. A component can then decide how to render the result without accidentally becoming the source of truth for persistence semantics.
Fixture: create, update, and delete
Use an isolated record per test. Verify the meaningful postcondition after each operation: a created record has its usable id, an update returns the fresh intended state, and a delete makes the record unavailable through the repository. Avoid relying on suite order or a shared mutable fixture.
Fixture: translated failure
Force or simulate the storage failure your repository claims to handle. The assertion is not that Firestore always emits one exact message; SDK messages and transport details can change. Assert your own safe result or error classification, plus enough contextual logging to diagnose the failure without exposing secrets or customer data.
An illustrative contract suite
The names below are illustrative, not copied from Accelerator. Adapt them to your domain and run them against the implementation you actually ship.
type Project = { id: string; ownerId: string; name: string };
interface ProjectRepository {
findById(id: string): Promise<Project | null>;
listByOwner(ownerId: string): Promise<Project[]>;
create(input: Omit<Project, "id">): Promise<Project>;
}
test("returns the stored project with a stable id", async () => {
await seedProject({ id: "project-a", ownerId: "owner-a", name: "Atlas" });
await expect(repository.findById("project-a")).resolves.toEqual({
id: "project-a", ownerId: "owner-a", name: "Atlas",
});
});
test("returns null when a project is absent", async () => {
await expect(repository.findById("missing")).resolves.toBeNull();
});This test does not render a component. It asks whether the persistence boundary keeps the promise the component will later consume. Add a separate UI test only where the screen’s behavior matters: loading state, empty-state wording, form submission, permission messaging, or navigation after success.
Run the same contract where it earns confidence
A fast in-memory test double is useful for pure domain behavior, but it cannot prove Firestore-specific mapping or query behavior. A local emulator can provide more realistic integration coverage without touching production data. Firebase describes the Local Emulator Suite as a way to run integration testing and QA against emulated services, and its documentation recommends clearing or otherwise isolating data between test cases.
Use a layered approach: run a small pure suite on every edit, run the Firestore-backed contract suite when adapter behavior changes, and run rules tests whenever client access policy changes. This keeps feedback fast without confusing speed with coverage.
Failure modes that UI-only tests hide
- Accidental id loss: a screen may look correct until a later update needs the document id that mapping dropped.
- Leaky storage shapes: components begin checking adapter-specific timestamp or document fields because the repository did not normalize them.
- Shared-fixture pollution: one test’s write changes another test’s expected list.
- False authorization confidence: an Admin-SDK test passes while a client rule was never evaluated.
- Unstable error handling: a provider message becomes user-visible because the repository never translated it into an application-level outcome.
When not to add another abstraction
Do not create a repository merely to wrap one one-off read. The boundary earns its cost when more than one caller needs the same persistence behavior, when provider details would otherwise spread, or when you need focused tests around mapping and failure handling. Keep it close to the feature when the behavior is feature-specific; extract it only when the contract is genuinely shared.
For a SaaS foundation, the goal is not to pretend that Firestore and every other database are identical. It is to make the chosen data behavior explicit enough that a change is reviewable, testable, and understandable. That gives an AI-assisted team a stable place to add work without teaching every component how persistence works.
A practical next step
- Choose one repository method with a real caller.
- Write the successful, empty, missing, and failure outcomes in plain language.
- Build isolated fixtures for those outcomes.
- Run the contract against the implementation that owns Firestore mapping.
- Add a distinct rules test for client authorization if the flow depends on Security Rules.
For related architecture work, see our guides to modeling a multi-tenant SaaS in Firestore and Firestore Security Rules for tenant isolation. If you want a Next.js SaaS foundation with database adapters and explicit project conventions, explore Frontend Accelerator’s features.
