Seed / Reset Test Data, Deterministic IDs / Clock Handling, and Parallel Test Isolation

1. AtlasMart flaky test: yesterday’s data is today’s bug

Two CI workers both use products/sku-1. One test advances an expiry field using the wall clock; another assumes the default seed still exists. Depending on test order and machine timing, the suite alternates between green and red. This is not a Firestore correctness problem—it is a test-isolation problem.

2. Four sources of nondeterminism

3. Seed state: source-controlled intent vs binary emulator snapshot

Use two seed forms for different jobs:

import { db } from "../src/admin-emulator.mjs";export const FIXED_NOW = new Date("2026-09-17T09:00:00.000Z");const products = [  ["t-red__p-001", { tenantId:"t-red", name:"Red Mug", active:true, schemaVersion:1 }],  ["t-red__p-002", { tenantId:"t-red", name:"Steel Bottle", active:true, schemaVersion:1 }],  ["t-blue__p-001", { tenantId:"t-blue", name:"Blue Mug", active:true, schemaVersion:1 }]];for (const [id, data] of products) {  await db.doc(`products/${id}`).set({ ...data, updatedAt: FIXED_NOW });}console.log(JSON.stringify({seedVersion:"atlasmart-v26-1", products:products.length}));

firebase emulators:start --project demo-atlasmart-firestore --only auth,firestore# in another terminal after reviewed seed has run:firebase emulators:export ./test/seed/atlasmart-v26 --force# CI can later use:firebase emulators:exec --project demo-atlasmart-firestore \  --only auth,firestore --import=./test/seed/atlasmart-v26 \  "npm test"

4. Reset must be awaited

The Firestore emulator exposes a test-only REST delete endpoint. A suite that fires the DELETE and immediately seeds can race its own cleanup. Await completion, then assert the database is empty or the seed version matches.

const project = "demo-atlasmart-firestore";const url = `http://127.0.0.1:8080/emulator/v1/projects/${project}/databases/(default)/documents`;const res = await fetch(url, { method: "DELETE" });if (!res.ok) throw new Error(`reset failed: ${res.status} ${await res.text()}`);console.log("firestore reset complete");

For Rules tests, RulesTestEnvironment.clearFirestore() is usually cleaner. Use the REST endpoint for broader integration harnesses that are not built around rules-unit-testing.

5. Clock handling: Firestore server timestamps are observable but not injectable

Domain decisions such as “is session expired?” should not be hidden behind direct calls to Date.now() inside transaction callbacks. Pass a clock into the application layer. Where you specifically need to test serverTimestamp(), assert shape/order properties rather than exact wall-clock equality.

export const realClock = { now: () => new Date() };export const fixedClock = iso => ({ now: () => new Date(iso) });export function nextExpiry(clock, ttlMs) {  return new Date(clock.now().getTime() + ttlMs);}// deterministic testconst clock = fixedClock("2026-09-17T09:00:00.000Z");console.assert(nextExpiry(clock, 60_000).toISOString() === "2026-09-17T09:01:00.000Z");

6. Deterministic IDs: identity semantics must survive migration tests

import { createHash } from "node:crypto";export function testId(worker, logicalKey) {  const h = createHash("sha256").update(`${worker}:${logicalKey}`).digest("hex").slice(0, 12);  return `${worker}__${h}`;}console.log(testId(process.env.TEST_WORKER_ID ?? "w0", "cart:u-17"));

Do not globally replace production auto IDs with semantic IDs just to simplify tests. Keep production ID strategy intact and inject deterministic IDs only at the repository/test seam where the domain permits it.

7. Parallel isolation strategies

Rules tests usually benefit from real collection paths plus serial or explicit reset. Large application suites can shard by separate emulator process/project ID, e.g. demo-atlasmart-firestore-w1, w2.

8. Offline cache trap

The Firestore emulator clears server-side state on shutdown/reset, but a mobile/web SDK cache can outlive the emulator state. In emulator integration tests, disable persistent cache or create fresh app instances and clear test persistence. Otherwise an assertion can observe cached data that no longer exists locally.

9. Mandatory lab: make failure reproducible

1. Create atlasmart-v26-1 seed with three products, two tenants and one order.
2. Write a test that intentionally uses Date.now() and a shared document; run it in parallel until it demonstrates nondeterminism.
3. Repair with injected clock and per-worker identity or serial reset.
4. Run the suite three times from emulators:exec --import; require identical test counts and migration-version distribution.
5. At teardown, assert no leaked listener handles and call cleanup.

set -euo pipefailfor i in 1 2 3; do  echo "=== deterministic pass $i ==="  firebase emulators:exec --project demo-atlasmart-firestore \    --only auth,firestore --import=./test/seed/atlasmart-v26 \    "npm run test:rules && npm run test:integration"done

10. Wrong approach: “random data makes tests realistic”

Unseeded randomness can expand coverage, but without a captured seed it destroys reproducibility. Property-based/fuzz tests should log the PRNG seed and minimal failing case. Deterministic integration fixtures should remain deterministic. Randomness is a test technique—not a substitute for fixture design.

Production judgment and bridge

Parallelism is valuable only if it does not change the model under test. Favor isolation you can explain and audit. Lesson 3 now versions the two other pieces that often drift outside CI: Security Rules and index definitions.

Knowledge check

1. Why must reset completion be awaited?
2. When is an emulator export preferable to readable fixture code?
3. Why inject a clock instead of mocking Firestore server timestamps everywhere?
4. Why can cached data invalidate reset-based tests?
5. What is the strongest parallel isolation?

Authoritative references

• Firebase: Connect your app to the Cloud Firestore Emulator — demo projects, edition selection, Admin SDK environment variables, reset/import/export, Rules reports, and production differences.
• Firebase: Install, configure and integrate Local Emulator Suite — emulators:exec, import/export and CI workflow.
• Firebase: Test Cloud Firestore Security Rules — emulator rules testing and CI execution.
• Firebase: Build Security Rules unit tests — @firebase/rules-unit-testing, mocked auth, clearing state and disabled-rules fixture setup.
• Firebase: Manage and deploy Security Rules — source control, local testing and selective deployment.
• Firebase: Manage indexes in Cloud Firestore — source-controlled index definitions and CLI deployment.
• Firebase: Cloud Firestore index definition reference — composite, field override and vector index JSON shapes.
• Firebase CLI reference — configured multi-database rules/indexes and deployment selectors.