Local Testing With the Firebase Emulator Suite

A complete guide to running Firebase emulators for developers with sample Flutter and Vue.js client apps

Photo by Oskar Yildiz on Unsplash

Software developers need to be able to run and debug their complete setup locally. Having a fully working local system allows them to be more productive by doing multiple things like:

• Developing and testing new features as well as debugging any potential problems.
• Removing dependency on shared data sources or systems when not needed.
• Debugging and stepping through the code while watching the program memory, variables in real-time without having to attach to a remote host.

A local setup can be tricky when working with a server-less environment. This article will look at how we can accomplish all of the above using the Firebase Local Emulator Suite.

What Will We Cover

We will cover the following in this tutorial:

• How to setup and start Firebase Emulators on your workstation
• How to populate a copy of your test database or populate dummy data in the local Firestore Emulator.
• How to ensure that the auth emulator runs smoothly (recently released).
• Optional: How to setup the Auth emulator locally.

The below are not covered:

• Storage emulator is not available.
• Push Notifications (FCM) is not needed.
• Firebase Realtime Database. Although the emulator works locally, we haven’t covered it as part of the tutorial since we don’t use the Realtime database.

For the services like Storage and FCM that don’t support local emulators, you can continue to use your existing development or staging project or create a separate Firebase project to avoid mixing the data with other environments.

Let’s Get to Work

The steps beyond this point should work once you have set up your project. Follow the official Firebase guides if you’re still not there.

Configure the Emulator suite

Set up the Emulator Suite using the below command that walks you through the configuration wizard. Alternatively, you can directly configure the emulators’ network ports and the paths to Security Rules definitions in the firebase.json file.

firebase init emulators

Choose functions, firestore, database to begin. We will go through the optional auth emulator, which has been recently released, as a final step below in the article.

Run the Emulator Suite

Navigate to your project directory in the terminal and start the emulators by running the command
firebase emulators:start

• You should see a confirmation message on the terminal.

Terminal view to verify the status of emulators

• Verify the status of emulators by opening the emulators’ suite link in your browser. You should see something like the below screen, which is your locally deployed Firebase instance and similar to the Firebase web console. Verify the status of different services like Firestore and Functions.

Web browser view to verify the status of emulators

Attach to Debugger in VS Code

Debugging your code with breakpoints can be very handy and help you develop new features or identify tricky bugs. You can do this by adding --inspect-functions at the end of the command to run emulators and configure your IDE to attach to your debugger. Below we include an example of how to do that using VS Code.

• Run commandfirebase emulators:start --inspect-functions
• Make sure your launch.json in VS Code for the firebase project has the below settings. This tells the VS Code to look for a running instance of Node application on the specific port.

• Navigate to the code that you intend to debug and insert a breakpoint in the Visual Studio Code file editor. Use the play button under the debug option and have fun.

Visual Studio Code File Editor With Breakpoint

• Check your terminal to confirm that the debugger has been successfully attached.

Terminal view to verify the attached debugger

Load Data Into Firestore

If you want to make your local emulator testing practical, you will most likely need to work with data. Check out this detailed guide if you need to populate data in your local Firestore instance or skip to the next steps if this is not needed.

Flutterfire With Local Emulator

We have created a separate configuration flavor of our Flutter app to work with the local emulator (just like we have flavors for development, staging, and production). This makes it really easy to switch between the configurations.

• If you are using the Firestore SDK in your Flutter app to interact with the Firestore collections and documents, add these lines around your Firebase initialize code. This will direct your device emulator running the Flutter app to connect with the local Firebase setup.

Connect Flutter app to the local Firestore emulator

• If you are using the Firebase HTTP/Callable Functions and/or have built an API around it, change your Base URL/API URL to connect to the locally deployed copy of your Firebase Functions (HTTP and Callable Functions). In our example, we changed it to:
  baseUrl: "http://localhost:5001/my-awesome-project/asia-east2"

That’s it. Running or debugging your Flutter project using an emulator on the same device should connect to local Firebase emulators.

Web App With Local Emulator

We are working with a Vue.js web app. The steps for your setup, including whether you are using Vue.js or any other framework, should be very similar but may vary slightly depending on how you connect to Firebase.

Before being initialized, we need to inform the application that it should work with the locally deployed emulators of Firebase. Below are the steps we followed for our Vue.js app:

• Open .env.development and update the values of these variables:
VUE_APP_API: http://localhost:5001/my-awesome-project/asia-east2
VUE_APP_LOCAL: true
• If you are using the Firestore SDK in your web app, you would need to direct the SDK to interact with the local Firestore emulator, similar to the Flutter app above.
• Run the app with the serve script

Changing the environment variables does not take effect till you restart the app. Make sure you don’t update the variable while serving the app. First, update the variable, and then run the serve script. By default, the Vue CLI runs the application on port 8080, which is the same as the one we’re using for emulating Firestore. So, if you run the Vue app before the Firestore emulator, the latter will fail. You can avoid this by running the Firebase emulators before the Vue app — this will make Vue CLI automatically choose a different port.

Optional: Setting Up Local Auth Emulator

Firebase recently announced that auth emulators are also available. It is up to you if you prefer to set up auth locally or stick to your actual project data on the cloud.

Follow these steps to configure the Auth emulator:

1. Make sure yourfirebase-admin package is greater than9.3.0
2. Run firebase init emulators(or add auth manually to firebase.json under the emulator's section and skip step 3,4)
3. Add the Auth emulator to the selection
4. Choose the default ports
5. Enable the UI
6. Download emulators

Lastly, you will need to tell your client apps to talk to the Authentication emulator like the below example for a web app:

firebase.auth().useEmulator('http://localhost:9099/')

Conclusion

I hope you’ve found this article useful, and setting up the local Firebase emulators helps you with your productivity. Thanks for reading, and please feel free to share your feedback or suggestions to make this guide simpler!