Implement useEmulator for Firestore

Author: samtstern

.changeset/clever-eyes-glow.md

@@ -0,0 +1,6 @@
+---
+'@firebase/firestore': minor
+'@firebase/firestore-types': minor
+---
+
+Add a useEmulator(host, port) method

packages/firebase/index.d.ts

@@ -8043,6 +8043,16 @@ declare namespace firebase.firestore {
      */
     settings(settings: Settings): void;
 
+    /**
+     * Modify this instance to communicate with the Cloud Firestore emulator.
+     *
+     * <p>Note: this must be called before this instance has been used to do any operations.
+     *
+     * @param host the emulator host (ex: localhost).
+     * @param port the emulator port (ex: 9000).
+     */
+    useEmulator(host: string, port: number): void;
+
     /**
      * Attempts to enable persistent storage, if possible.
      *

packages/firestore-types/index.d.ts

@@ -61,6 +61,8 @@ export class FirebaseFirestore {
 
   settings(settings: Settings): void;
 
+  useEmulator(host: string, port: number): void;
+
   enablePersistence(settings?: PersistenceSettings): Promise<void>;
 
   collection(collectionPath: string): CollectionReference<DocumentData>;

packages/firestore/exp/test/shim.ts

@@ -99,6 +99,10 @@ export class FirebaseFirestore
     initializeFirestore(this.app._delegate, settings);
   }
 
+  useEmulator(host: string, port: number) {
+    this.settings({ host: `${host}:${port}`, ssl: false, merge: true });
+  }
+
   enablePersistence(settings?: legacy.PersistenceSettings): Promise<void> {
     return settings?.synchronizeTabs
       ? enableMultiTabIndexedDbPersistence(this._delegate)

packages/firestore/src/api/database.ts

@@ -108,7 +108,13 @@ import {
   validateStringEnum,
   valueDescription
 } from '../util/input_validation';
-import { getLogLevel, logError, LogLevel, setLogLevel } from '../util/log';
+import {
+  getLogLevel,
+  logError,
+  LogLevel,
+  setLogLevel,
+  logWarn
+} from '../util/log';
 import { AutoId } from '../util/misc';
 import { Deferred } from '../util/promise';
 import { FieldPath as ExternalFieldPath } from './field_path';
@@ -413,6 +419,32 @@ export class Firestore implements PublicFirestore, FirebaseService {
     }
   }
 
+  useEmulator(host: string, port: number) {
+    validateExactNumberOfArgs('Firestore.useEmulator', arguments, 2);
+    validateArgType('Firestore.useEmulator', 'string', 1, host);
+    validateArgType('Firestore.useEmulator', 'number', 2, port);
+
+    if (this._firestoreClient) {
+      throw new FirestoreError(
+        Code.FAILED_PRECONDITION,
+        'Firestore hass already been started and its settings can no longer be changed. ' +
+          'You can only call useEmulator() before calling any other methods on a Firestore object.'
+      );
+    }
+
+    if (this._settings.host !== DEFAULT_HOST) {
+      logWarn(
+        'Host has been set in both settings() and useEmulator(), emulator host will be used'
+      );
+    }
+
+    this.settings({
+      host: `${host}:${port}`,
+      ssl: false,
+      merge: true
+    });
+  }
+
   enableNetwork(): Promise<void> {
     this.ensureClientConfigured();
     return this._firestoreClient!.enableNetwork();

packages/firestore/test/integration/api/validation.test.ts

@@ -182,6 +182,25 @@ apiDescribe('Validation:', (persistence: boolean) => {
       // Verify that this doesn't throw.
       db.settings({ cacheSizeBytes: /* CACHE_SIZE_UNLIMITED= */ -1 });
     });
+
+    validationIt(persistence, 'useEmulator can set host and port', () => {
+      const db = newTestFirestore('test-project');
+      // Verify that this doesn't throw.
+      db.useEmulator('localhost', 9000);
+    });
+
+    validationIt(
+      persistence,
+      'disallows calling useEmulator after use',
+      async db => {
+        const errorMsg =
+          'Firestore hass already been started and its settings can no longer be changed. ' +
+          'You can only call useEmulator() before calling any other methods on a Firestore object.';
+
+        await db.doc('foo/bar').set({});
+        expect(() => db.useEmulator('localhost', 9000)).to.throw(errorMsg);
+      }
+    );
   });
 
   describe('Firestore', () => {

packages/firestore/test/unit/api/database.test.ts

@@ -182,4 +182,23 @@ describe('Settings', () => {
     expect(firestoreClient._getSettings().ignoreUndefinedProperties).to.be.true;
     expect(firestoreClient._getSettings().host).to.equal('other.host');
   });
+
+  it('gets settings from useEmulator', () => {
+    // Use a new instance of Firestore in order to configure settings.
+    const firestoreClient = newTestFirestore();
+    firestoreClient.useEmulator('localhost', 9000);
+
+    expect(firestoreClient._getSettings().host).to.equal('localhost:9000');
+    expect(firestoreClient._getSettings().ssl).to.be.false;
+  });
+
+  it('prefers host from useEmulator to host from settings', () => {
+    // Use a new instance of Firestore in order to configure settings.
+    const firestoreClient = newTestFirestore();
+    firestoreClient.settings({ host: 'other.host' });
+    firestoreClient.useEmulator('localhost', 9000);
+
+    expect(firestoreClient._getSettings().host).to.equal('localhost:9000');
+    expect(firestoreClient._getSettings().ssl).to.be.false;
+  });
 });