Implement useEmulator for Functions (#3906)

Author: samtstern

.changeset/silver-books-reply.md

@@ -0,0 +1,8 @@
+---
+'firebase': minor
+'@firebase/functions-exp': minor
+'@firebase/functions': minor
+'@firebase/functions-types': minor
+---
+
+Add a useEmulator(host, port) method to Cloud Functions

packages-exp/functions-exp/src/api.ts

@@ -56,18 +56,20 @@ export function getFunctions(
 }
 
 /**
- * Changes this instance to point to a Cloud Functions emulator running
- * locally. See https://firebase.google.com/docs/functions/local-emulator
+ * Modify this instance to communicate with the Cloud Functions emulator.
  *
- * @param origin - The origin of the local emulator, such as
- * "http://localhost:5005".
+ * 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: 5001)
  * @public
  */
 export function useFunctionsEmulator(
   functionsInstance: Functions,
-  origin: string
+  host: string,
+  port: number
 ): void {
-  _useFunctionsEmulator(functionsInstance as FunctionsService, origin);
+  _useFunctionsEmulator(functionsInstance as FunctionsService, host, port);
 }
 
 /**

packages-exp/functions-exp/src/service.test.ts

@@ -41,7 +41,7 @@ describe('Firebase Functions > Service', () => {
 
     it('can use emulator', () => {
       service = createTestService(app);
-      useFunctionsEmulator(service, 'http://localhost:5005');
+      useFunctionsEmulator(service, 'localhost', 5005);
       assert.equal(
         service._url('foo'),
         'http://localhost:5005/my-project/us-central1/foo'
@@ -58,7 +58,7 @@ describe('Firebase Functions > Service', () => {
 
     it('correctly sets region with emulator', () => {
       service = createTestService(app, 'my-region');
-      useFunctionsEmulator(service, 'http://localhost:5005');
+      useFunctionsEmulator(service, 'localhost', 5005);
       assert.equal(
         service._url('foo'),
         'http://localhost:5005/my-project/my-region/foo'
@@ -72,7 +72,7 @@ describe('Firebase Functions > Service', () => {
 
     it('prefers emulator to custom domain', () => {
       const service = createTestService(app, 'https://mydomain.com');
-      useFunctionsEmulator(service, 'http://localhost:5005');
+      useFunctionsEmulator(service, 'localhost', 5005);
       assert.equal(
         service._url('foo'),
         'http://localhost:5005/my-project/us-central1/foo'

packages-exp/functions-exp/src/service.ts

@@ -133,18 +133,20 @@ export class FunctionsService implements _FirebaseService {
 }
 
 /**
- * Changes this instance to point to a Cloud Functions emulator running
- * locally. See https://firebase.google.com/docs/functions/local-emulator
+ * Modify this instance to communicate with the Cloud Functions emulator.
  *
- * @param origin - The origin of the local emulator, such as
- * "http://localhost:5005".
+ * 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: 5001)
  * @public
  */
 export function useFunctionsEmulator(
   functionsInstance: FunctionsService,
-  origin: string
+  host: string,
+  port: number
 ): void {
-  functionsInstance.emulatorOrigin = origin;
+  functionsInstance.emulatorOrigin = `http://${host}:${port}`;
 }
 
 /**

packages-exp/functions-exp/test/utils.ts

@@ -64,10 +64,11 @@ export function createTestService(
   );
   const useEmulator = !!process.env.FIREBASE_FUNCTIONS_EMULATOR_ORIGIN;
   if (useEmulator) {
+    const url = new URL(process.env.FIREBASE_FUNCTIONS_EMULATOR_ORIGIN!);
     useFunctionsEmulator(
       functions,
-      process.env.FIREBASE_FUNCTIONS_EMULATOR_ORIGIN!
-    );
+      url.hostname,
+      Number.parseInt(url.port, 10));
   }
   return functions;
 }

packages/firebase/index.d.ts

@@ -1799,10 +1799,22 @@ declare namespace firebase.functions {
    */
   export class Functions {
     private constructor();
+
+    /**
+     * Modify this instance to communicate with the Cloud Functions emulator.
+     *
+     * 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: 5001)
+     */
+    useEmulator(host: string, port: number): void;
+
     /**
      * Changes this instance to point to a Cloud Functions emulator running
      * locally. See https://firebase.google.com/docs/functions/local-emulator
-     *
+     * 
+     * @deprecated Prefer the useEmulator(host, port) method.
      * @param origin The origin of the local emulator, such as
      * "http://localhost:5005".
      */

packages/functions-types/index.d.ts

@@ -53,10 +53,21 @@ export class FirebaseFunctions {
    */
   httpsCallable(name: string, options?: HttpsCallableOptions): HttpsCallable;
 
+  /**
+   * Modify this instance to communicate with the Cloud Functions emulator.
+   *
+   * 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: 5001)
+   */
+  useEmulator(host: string, port: number): void;
+
   /**
    * Changes this instance to point to a Cloud Functions emulator running
    * locally. See https://firebase.google.com/docs/functions/local-emulator
    *
+   * @deprecated Prefer the useEmulator(host, port) method.
    * @param origin The origin of the local emulator, such as
    * "http://localhost:5005".
    */

packages/functions/src/api/service.ts

@@ -150,10 +150,23 @@ export class Service implements FirebaseFunctions, FirebaseService {
     return `https://${this.region}-${projectId}.cloudfunctions.net/${name}`;
   }
 
+  /**
+   * Modify this instance to communicate with the Cloud Functions emulator.
+   *
+   * 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: 5001)
+   */
+  useEmulator(host: string, port: number): void {
+    this.emulatorOrigin = `http://${host}:${port}`;
+  }
+
   /**
    * Changes this instance to point to a Cloud Functions emulator running
    * locally. See https://firebase.google.com/docs/functions/local-emulator
    *
+   * @deprecated Prefer the useEmulator(host, port) method.
    * @param origin The origin of the local emulator, such as
    * "http://localhost:5005".
    */

packages/functions/test/service.test.ts

@@ -33,13 +33,21 @@ describe('Firebase Functions > Service', () => {
       );
     });
 
-    it('can use emulator', () => {
+    it('can use emulator (deprecated)', () => {
       service.useFunctionsEmulator('http://localhost:5005');
       assert.equal(
         service._url('foo'),
         'http://localhost:5005/my-project/us-central1/foo'
       );
     });
+
+    it('can use emulator', () => {
+      service.useEmulator('localhost', 5005);
+      assert.equal(
+        service._url('foo'),
+        'http://localhost:5005/my-project/us-central1/foo'
+      );
+    });
   });
 
   describe('custom region/domain constructor', () => {
@@ -62,13 +70,22 @@ describe('Firebase Functions > Service', () => {
       assert.equal(service._url('foo'), 'https://mydomain.com/foo');
     });
 
-    it('prefers emulator to custom domain', () => {
+    it('prefers emulator to custom domain (deprecated)', () => {
       const service = createTestService(app, 'https://mydomain.com');
       service.useFunctionsEmulator('http://localhost:5005');
       assert.equal(
         service._url('foo'),
         'http://localhost:5005/my-project/us-central1/foo'
       );
     });
+
+    it('prefers emulator to custom domain', () => {
+      const service = createTestService(app, 'https://mydomain.com');
+      service.useEmulator('localhost', 5005);
+      assert.equal(
+        service._url('foo'),
+        'http://localhost:5005/my-project/us-central1/foo'
+      );
+    });
   });
 });