Emulator Suite for Firestore / Auth / Functions-Like Integration Testing and Known Differences from Production

1. AtlasMart release candidate: green locally, unknown in production

AtlasMart has a release candidate that passes unit tests, reads and writes correctly against the local Firestore emulator, and signs in through the Auth emulator. The team is tempted to call that “production verified.” That conclusion is too strong. The emulator is a behavioral development and integration environment, not a proof of managed indexes, quota enforcement, production contention, IAM, billing, network topology, App Check enforcement, recovery features, or production latency.

Chapter 26 turns that gap into an explicit delivery system. Local tests must prove deterministic application and Security Rules behavior; a small production canary must prove only the managed-service properties the emulator cannot model.

2. Vocabulary: what each test surface proves

3. Use a demo project as the hard safety boundary

A Firebase demo project uses a demo- prefix and has no live resources. If code attempts to call a Firebase product whose emulator is not running, the request fails instead of falling through to production. That makes demo-atlasmart-firestore the right mandatory CI project ID.

{  "firestore": {    "rules": "firestore.rules",    "indexes": "firestore.indexes.json",    "edition": "standard"  },  "emulators": {    "auth": { "host": "127.0.0.1", "port": 9099 },    "firestore": { "host": "127.0.0.1", "port": 8080 },    "ui": { "host": "127.0.0.1", "port": 4000 }  }}

{  "scripts": {    "test:rules": "node --test test/rules/*.test.mjs",    "test:integration": "node --test test/integration/*.test.mjs",    "ci:firebase": "firebase emulators:exec --project demo-atlasmart-firestore --only auth,firestore 'npm run test:rules && npm run test:integration'"  }}

All SDKs, emulators and locally emulated Functions must use the same project ID. That identity is how the suite wires Firestore/Auth/Functions interactions together.

4. Client path vs server path: test the correct trust boundary

process.env.FIRESTORE_EMULATOR_HOST = "127.0.0.1:8080";process.env.GCLOUD_PROJECT = "demo-atlasmart-firestore";import { initializeApp } from "firebase-admin/app";import { getFirestore } from "firebase-admin/firestore";initializeApp({ projectId: "demo-atlasmart-firestore" });export const db = getFirestore();

5. Known Firestore emulator differences are release-gate inputs

6. Rules-first integration test with clean state

import fs from "node:fs";import test from "node:test";import assert from "node:assert/strict";import {  initializeTestEnvironment,  assertSucceeds,  assertFails} from "@firebase/rules-unit-testing";import { doc, getDoc, setDoc } from "firebase/firestore";let env;test.before(async () => {  env = await initializeTestEnvironment({    projectId: "demo-atlasmart-firestore",    firestore: { rules: fs.readFileSync("firestore.rules", "utf8") }  });});test.beforeEach(async () => {  await env.clearFirestore();  await env.withSecurityRulesDisabled(async ctx => {    await setDoc(doc(ctx.firestore(), "products", "sku-red-1"), {      tenantId: "t-red", visibility: "tenant", active: true,      schemaVersion: 1, name: "Red Mug"    });  });});test("tenant can read own product", async () => {  const db = env.authenticatedContext("u-red", { tenantId: "t-red" }).firestore();  await assertSucceeds(getDoc(doc(db, "products", "sku-red-1")));});test("other tenant is denied", async () => {  const db = env.authenticatedContext("u-blue", { tenantId: "t-blue" }).firestore();  await assertFails(getDoc(doc(db, "products", "sku-red-1")));});test.after(async () => env.cleanup());

withSecurityRulesDisabled seeds fixtures without converting your fixture loader into a privileged production pattern. Each request test then executes with an explicit auth context.

7. Functions-like integration: assert idempotency, not delivery folklore

export async function handleOrderCreated(event, db) {  const eventRef = db.doc(`eventReceipts/${event.id}`);  const orderRef = db.doc(`orders/${event.orderId}`);  await db.runTransaction(async tx => {    const receipt = await tx.get(eventRef);    if (receipt.exists) return; // duplicate delivery is harmless    tx.set(eventRef, { processedAt: event.now, source: "order-created" });    tx.update(orderRef, { workflowState: "accepted" });  });}

The local test can deliberately invoke the handler twice with the same event ID and assert one receipt and one state transition. It does not claim a particular production event-delivery latency or ordering guarantee.

8. Mandatory lab: CI contract

1. Save firebase.json, firestore.rules, and firestore.indexes.json under version control.
2. Use demo-atlasmart-firestore; verify no non-emulated product is required by the mandatory tests.
3. Run firebase emulators:exec --project demo-atlasmart-firestore --only auth,firestore "npm run test:rules && npm run test:integration".
4. At test start, clear Firestore or import a known seed; never depend on prior emulator state.
5. Capture Rules test results, rule coverage endpoint, migration-version counts, and backfill checkpoints as CI artifacts.
6. Maintain a separate production-canary checklist for indexes, IAM, limits, App Check, billing/metrics and latency.

9. Controlled failure: emulator as performance oracle

Wrong approach: run 20,000 local writes, observe a high operations/second number, then size production around it. The local process has different storage, networking, index enforcement and contention behavior. The number answers “how fast did this laptop/emulator execute this script?”—not “what production can sustain?”

Repair: keep the emulator benchmark only as a regression detector for your code path. Define a separate, bounded, billable pre-production load test with stop conditions and compare p50/p95/p99, errors, Query Explain/index evidence, and cost signals there.

Production judgment and bridge

A strong CI pipeline does not maximize emulator coverage; it assigns each requirement to the cheapest environment that can actually prove it. Local tests should be exhaustive for deterministic business logic and Rules. Cloud tests should be narrow, isolated and evidence-driven for managed-service properties. Lesson 2 makes that local layer reproducible under seed/reset, clocks, IDs and parallelism.

Knowledge check

1. Why is a demo project safer than a real project for mandatory CI?
2. What production property cannot be proven by a compound query passing in the emulator?
3. Why must Admin SDK tests not be interpreted as Rules tests?
4. What should a Functions-like test assert under duplicate delivery?
5. What belongs in the production-canary contract?

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.