chore(firestore): improve contributor documentation and test infra (#9864)

dlarocque · web-flow · commit 77018d7c5f05 · 2026-04-21T13:22:14.000-04:00
diff --git a/packages/firestore/CONTRIBUTING.md b/packages/firestore/CONTRIBUTING.md
@@ -7,70 +7,118 @@ the testing environment.
 
 ## Integration Testing
 
-### Setting up a project for testing
+### Setting up the Firestore emulator
 
-You will need a production project to test the Firestore SDK. You can create
-a new project by visiting the 
-[Firebase Console](https://console.firebase.google.com/). Make sure that the 
-project has Cloud Firestore enabled in the database section of the console.
+Integration tests that run against the Firestore emulator expect
+that it runs on port 8080.
+
+- [Install the Firebase CLI](https://firebase.google.com/docs/cli/).
+  ```bash
+  npm install -g firebase-tools
+  ```
+- [Install the Firestore emulator](https://firebase.google.com/docs/firestore/security/test-rules-emulator#install_the_emulator).
+  ```bash
+  firebase setup:emulators:firestore
+  ```
+- Run the emulator:
+  ```bash
+  firebase emulators:start --only firestore
+  ```
+
+## Testing Firestore
+
+Testing Firestore is organized along three dimensions:
+
+1.  **Environment**: Where the code runs.
+    - **Node.js**: Fast, V8-based testing using Mocha. Perfect for logic that doesn't require a browser.
+    - **Browsers**: Uses Karma to run tests in real browser engines (Chrome, Firefox, WebKit). Essential for testing IndexedDB and WebChannels.
+2.  **SDK Type**: Which version of the SDK is being tested.
+    - **Full SDK**: Includes real-time listeners, offline persistence, and caching.
+    - **Lite SDK**: A REST-only, lightweight version without persistence or real-time support.
+3.  **Backend**: Which server the tests communicate with.
+    - **Emulator**: Local server (default).
+    - **Production**: The live Firebase backend.
+    - **Nightly**: Pre-release backend for catching upcoming server changes.
+
+### Running Tests
+
+All commands must be run from the `packages/firestore/` directory.
+
+```bash
+# Full SDK - Node (Emulator)
+yarn test:node
 
-See 
-[Automated Setup](https://github.com/firebase/firebase-js-sdk#automated-setup) 
-for more details.
+# Full SDK - Browser (Chrome Headless, Emulator)
+yarn test:browser
 
-### Setting up the Firestore emulator
+# Lite SDK - Node (Emulator)
+yarn test:lite
 
-The integration tests require that the Firestore emulator is running
-on port 8080, which is default when running it via CLI.
+# Lite SDK - Browser (Chrome Headless, Emulator)
+yarn test:lite:browser
+```
 
-  * [Install the Firebase CLI](https://firebase.google.com/docs/cli/).
-    ```
-    npm install -g firebase-tools
-    ```
-  * [Install the Firestore
-    emulator](https://firebase.google.com/docs/firestore/security/test-rules-emulator#install_the_emulator).
-    ```
-    firebase setup:emulators:firestore
-    ```
-  * Run the emulator
-    ```
-    firebase emulators:start --only firestore
-    ```
+### Environment Variables & Flags
 
-### Running Firestore Tests
+Use these variables to change the target backend or database:
 
-All commands must be run from the `packages/firestore/` directory. 
+- **`FIRESTORE_TARGET_BACKEND`**: Set to `emulator`, `prod`, or `nightly`. `nightly` is only available to Googlers.
+- **`FIRESTORE_TARGET_DB_ID`**: Targets a specific database ID (default is `(default)`).
+- **`--firestoreEdition=enterprise`**: Enables enterprise-specific tests (sets `RUN_ENTERPRISE_TESTS=true`).
+- **`BROWSERS`**: (Browser tests only) A comma-separated list of browsers: `ChromeHeadless`, `Firefox`, `WebkitHeadless`.
+  - Example: `BROWSERS=Firefox,WebkitHeadless yarn test:browser`
 
-```
-# Come up to date on dependencies after performing git pull
-(cd ../../; yarn && yarn build)
+### Persistence
 
-# Run all tests once (browser and node)
-yarn test
+- **Browsers**: Persistence (IndexedDB) is tested natively.
+- **Node.js**: Node lacks a native database. Use `yarn test:node:persistence` to enable a mock persistence layer for testing offline logic in Node.
 
-# Run all browser tests once (unit and integration)
-yarn test:browser
+### Filtering Tests (Grep)
 
-# Debug browser tests in Chrome and keep the browser open (and watch for file
-# changes).
-yarn test:browser:debug
+Use the `--grep` flag to run specific tests.
 
-# Run only the browser unit or integration tests
-yarn test:browser --unit
-yarn test:browser --integration
+```bash
+yarn test:node --grep 'SortedSet'
+yarn test:browser --grep 'Query'
+```
 
-# Run browser integration tests against a Firestore server running on
-# localhost:8080.
-yarn test:browser:emulator --integration
+## Testing Firestore Pipelines
 
-# Run all node tests once (unit and integration) against the emulator.
-yarn test:node
+### Enterprise Edition & Database IDs
+
+To test Pipeline features that require the Enterprise backend:
+
+- **Named Databases**: Use a database ID other than `(default)`. In our automated tests, we typically use the ID `enterprise`.
+- **Edition Flag**: Pass `--firestoreEdition=enterprise` to enable Enterprise-specific test cases and assertions.
 
-# Run a subset of tests whose names match a filter.
-yarn test:browser --grep 'SortedSet keeps elements in the right order'
-yarn test:node --grep 'SortedSet keeps elements in the right order'
+Example: Running Pipeline integration tests against production with an enterprise database:
 
-# Run tests against the production backend.
-yarn test:node:prod
-yarn test:node:persistence:prod
+```bash
+yarn test:node:prod:enterprise --grep 'Pipeline'
 ```
+
+### Testing Environments for Pipelines
+
+- **Emulator**: Supports basic pipeline structures and some aggregations.
+- **Nightly**: Preferred for testing new Pipeline features before they reach Production. Use `FIRESTORE_TARGET_BACKEND=nightly`.
+- **Production**: Used for final validation of released Pipeline features.
+
+## Debugging
+
+### CLI Debugging
+
+We provide `:debug` scripts that wait for a debugger to attach:
+
+- **Node**: `yarn test:node:debug` (uses `node --inspect-brk`).
+- **Browser**: `yarn test:browser:debug` (keeps Chrome open and watches for file changes).
+
+### VSCode Debugging
+
+Use the **Run and Debug** pane in VSCode. Recommended configurations:
+
+- **Firestore Unit Tests (Node)**: Fast debugging for Node logic.
+- **Firestore Integration Tests (Node)**: Debugs against the emulator.
+- **Firestore Integration Tests (Browser)**: Debugs in Chrome.
+- **Firestore Enterprise Lite Tests**: Debugs Lite SDK against Nightly/Enterprise.
+
+Most configurations will prompt you for a `grepString` to filter tests before starting.
diff --git a/packages/firestore/package.json b/packages/firestore/package.json
@@ -45,6 +45,8 @@
     "test:node": "ts-node ./scripts/run-tests.ts  --main=test/register.ts  --emulator 'test/{,!(browser|lite)/**/}*.test.ts'",
     "test:node:prod": "ts-node ./scripts/run-tests.ts --main=test/register.ts 'test/{,!(browser|lite)/**/}*.test.ts'",
     "test:node:prod:enterprise": "ts-node ./scripts/run-tests.ts --main=test/register.ts --databaseId=enterprise  --firestoreEdition=enterprise 'test/{,!(browser|lite)/**/}*.test.ts'",
+    "test:node:nightly": "ts-node ./scripts/run-tests.ts --main=test/register.ts 'test/{,!(browser|lite)/**/}*.test.ts' --targetBackend=nightly",
+    "test:node:debug": "ts-node ./scripts/run-tests.ts --main=test/register.ts --emulator --debug 'test/{,!(browser|lite)/**/}*.test.ts'",
     "test:node:persistence": "ts-node ./scripts/run-tests.ts  --main=test/register.ts --persistence --emulator 'test/{,!(browser|lite)/**/}*.test.ts'",
     "test:node:persistence:prod": "ts-node ./scripts/run-tests.ts --main=test/register.ts --persistence 'test/{,!(browser|lite)/**/}*.test.ts'",
     "test:travis": "ts-node --compiler-options='{\"module\":\"commonjs\"}' ../../scripts/emulator-testing/firestore-test-runner.ts",
diff --git a/packages/firestore/scripts/run-tests.ts b/packages/firestore/scripts/run-tests.ts
@@ -46,6 +46,14 @@ const argv = yargs
       type: 'string',
       description: 'Filter tests by name (regex)'
     },
+    targetBackend: {
+      type: 'string',
+      description: 'The backend to test against (emulator, prod, nightly)'
+    },
+    debug: {
+      type: 'boolean',
+      description: 'Run tests in debug mode (node --inspect-brk)'
+    }
   })
   .parseSync();
 
@@ -57,6 +65,11 @@ const babel = resolve(__dirname, '../babel-register.js');
 process.env.NO_TS_NODE = 'true';
 process.env.TEST_PLATFORM = argv.platform;
 
+if (argv.targetBackend) {
+  process.env.FIRESTORE_TARGET_BACKEND = argv.targetBackend;
+}
+
+let executable = nyc;
 let args = [
   '--reporter',
   'lcovonly',
@@ -69,6 +82,22 @@ let args = [
   '../../config/mocharc.node.js'
 ];
 
+if (argv.debug) {
+  // Bypassing nyc for debug mode
+  executable = 'node';
+  args = [
+    '--inspect-brk',
+    mocha,
+    '--require',
+    babel,
+    '--require',
+    argv.main,
+    '--config',
+    '../../config/mocharc.node.js',
+    '--no-timeouts'
+  ];
+}
+
 if (argv.emulator) {
   process.env.FIRESTORE_TARGET_BACKEND = 'emulator';
 }
@@ -94,7 +123,7 @@ if (argv.grep) {
 
 args = args.concat(argv._ as string[]);
 
-const spawnPromise = spawn(nyc, args, {
+const spawnPromise = spawn(executable, args, {
   stdio: 'inherit',
   cwd: process.cwd()
 });
@@ -104,11 +133,13 @@ const childProcess = spawnPromise.childProcess;
 spawnPromise.catch(error => {
   // When a test fails, there will be a non-zero error code. Simply exit this process,
   // and don't print a stack trace.
-  if (typeof error.code === 'number') {
+  // Note: error.code is the exit code of the spawned process.
+  if (typeof error.code === 'number' && error.code > 0) {
+    // If it's a standard test failure (mocha exit code), we don't need a runner stack trace.
     process.exit(error.code);
   } else {
-    // The error code will not be a number for a real crash (e.g., spawn
-    // failed to start), so print the entire stack trace for debugging.
+    // For other errors (spawn failed, runner crash, etc.), print the stack trace.
+    console.error('Test runner failed to execute:');
     console.error(error);
     process.exit(1);
   }
