Instalar, configurar e integrar la Suite del Emulador Local

La Suite de emuladores de Firebase se puede instalar y configurar para diferentes entornos de prototipado y prueba, desde sesiones de prototipado puntuales hasta flujos de trabajo de integración continua a escala de producción.

Instalar la Suite del Emulador Local

Antes de instalar la Suite de emuladores, necesitarás lo siguiente:

  • Node.js versión 16.0 o posterior.
  • Java JDK versión 11 o posterior.

Para instalar la Suite del emulador:

  1. Instala la CLI de Firebase. Si aún no has instalado la CLI de Firebase, hazlo ahora. Necesitarás la versión 8.14.0 o una posterior de la CLI para usar la Suite del emulador. Puedes comprobar qué versión tienes instalada con el siguiente comando:
    firebase --version
  2. Si aún no lo has hecho, inicializa el directorio de trabajo actual como un proyecto de Firebase siguiendo las indicaciones que aparecen en pantalla para especificar qué productos quieres usar:
    firebase init
  3. Configura Suite de emuladores. Este comando inicia un asistente de configuración que te permite seleccionar los emuladores que te interesen, descargar los archivos binarios correspondientes y definir los puertos de los emuladores si los predeterminados no son adecuados.
    firebase init emulators

Una vez instalado un emulador, no se comprueba si hay actualizaciones ni se realizan descargas automáticas adicionales hasta que actualices la versión de la CLI de Firebase.

Configurar Suite de emuladores

Si quieres, puedes configurar los puertos de red de los emuladores y la ruta a las definiciones de las reglas de seguridad en el archivo firebase.json:

  • Cambia los puertos del emulador ejecutando firebase init emulators o editando firebase.json manualmente.
  • Cambia la ruta de las definiciones de las reglas de seguridad editando firebase.json manualmente.

Si no configuras estos ajustes, los emuladores escucharán en sus puertos predeterminados, y los emuladores de Cloud Firestore, Realtime Database y Cloud Storage for Firebase se ejecutarán con seguridad de los datos abierta.

Comando Descripción
init emulators Inicia un asistente de inicialización del emulador. Identifica los emuladores que se van a instalar y, si quieres, especifica la configuración de los puertos de los emuladores. init emulators no es destructivo. Si aceptas los valores predeterminados, se conservará la configuración actual del emulador.

Configuración de puertos

Cada emulador se vincula a un puerto diferente de tu máquina con un valor predeterminado preferido.

Emulador Puerto predeterminado
Authentication 9099
App Hosting 5002
Emulator Suite UI 4000
Cloud Functions 5001
Eventarc 9299
Realtime Database 9000
Cloud Firestore 8080
Cloud Storage for Firebase 9199
Firebase Hosting 5000
Pub/Sub 8085

Configuración del ID de proyecto

En función de cómo invoques los emuladores, puedes ejecutar varias instancias de un emulador con diferentes IDs de proyecto de Firebase o varias instancias de emulador para un ID de proyecto determinado. En estos casos, las instancias del emulador se ejecutan en un entorno independiente.

Por lo general, se recomienda definir un ID de proyecto para todas las invocaciones de emuladores, de modo que Emulator Suite UI, los emuladores de diferentes productos y todas las instancias en ejecución de un emulador concreto puedan comunicarse correctamente en todos los casos.

Local Emulator Suite emite advertencias cuando detecta varios IDs de proyecto en el entorno, aunque puedes anular este comportamiento asignando el valor false a la clave singleProjectMode en tu firebase.json.

Puedes comprobar si hay discrepancias en las declaraciones de IDs de proyecto en:

  • El proyecto predeterminado en la línea de comandos. De forma predeterminada, el ID del proyecto se obtendrá al iniciarse el proyecto seleccionado con firebase init o firebase use. Para ver la lista de proyectos (y ver cuál está seleccionado), usa firebase projects:list.
  • Pruebas unitarias de reglas. El ID del proyecto se suele especificar en las llamadas a los métodos initializeTestEnvironment o initializeTestApp de la biblioteca de pruebas unitarias de reglas.
  • La marca de línea de comandos --project. Si se pasa la marca de CLI Firebase --project, se anula el proyecto predeterminado. Debes asegurarte de que el valor de la marca coincida con el ID del proyecto en las pruebas unitarias y en la inicialización de la aplicación.

Comprueba también las configuraciones de ID de proyecto específicas de la plataforma que hayas definido al configurar tus proyectos de plataformas de Apple, Android y Web.

Configuración de reglas de seguridad

Los emuladores tomarán la configuración de las reglas de seguridad de las claves de configuración database, firestore y storage de firebase.json.

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore": {
    "rules": "firestore.rules"
  },
  "storage": {
    "rules": "storage.rules"
  }

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "singleProjectMode": false, // do not warn on detection of multiple project IDs
    "firestore": {
      "port": "8080"
    },
    "ui": {
      "enabled": true,      // Default is `true`
      "port": 4000          // If unspecified, see CLI log for selected port
    },
    "auth": {
      "port": "9099"
    },
    "pubsub": {
      "port": "8085"
    }
  }
}

Especificar opciones de Java

El emulador de Realtime Database, el emulador de Cloud Firestore y parte del emulador de Cloud Storage for Firebase se basan en Java, que se puede personalizar con marcas de JVM mediante la variable de entorno JAVA_TOOL_OPTIONS.

Por ejemplo, si se producen errores relacionados con el espacio de montón de Java, puedes aumentar el tamaño máximo del montón de Java a 4 GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

Se pueden especificar varias marcas entre comillas separadas por espacios, como JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g". Las marcas solo afectan a los componentes basados en Java de los emuladores y no tienen ningún efecto en otras partes de la CLI de Firebase, como Emulator Suite UI.

Iniciar emuladores

Puedes iniciar emuladores para que se ejecuten hasta que se finalicen manualmente o para que se ejecuten durante el tiempo que dure un script de prueba designado y, después, se apaguen automáticamente.

Comando Descripción
emulators:start

Inicia emuladores para los productos de Firebase configurados en firebase.json. Los procesos del emulador seguirán ejecutándose hasta que se detengan de forma explícita. Al llamar a emulators:start, se descargarán los emuladores en ~/.cache/firebase/emulators/ si aún no están instalados.

Marcar Descripción
--only Opcional. Limitar qué emuladores se inician. Proporciona una lista separada por comas con los nombres de los emuladores, especificando uno o varios de los siguientes: auth, database, firestore, functions, hosting o pubsub.
--inspect-functions DEBUG_PORT Opcional. Se usa con el emulador Cloud Functions para habilitar la depuración de puntos de interrupción de funciones en el puerto especificado (o en el puerto predeterminado 9229 si se omite el argumento). Ten en cuenta que, cuando se proporciona esta marca, el emulador de Cloud Functions cambia a un modo de ejecución serializado especial en el que las funciones se ejecutan en un solo proceso, en orden secuencial (por orden de llegada). Esto simplifica la depuración de funciones, aunque el comportamiento difiere de la ejecución paralela de funciones en varios procesos en la nube.
--export-on-exit= Opcional. Úsalo con el emulador de Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Indica a los emuladores que exporten datos a un directorio cuando se produzca un cierre, tal como se describe en el comando emulators:export. El directorio de exportación se puede especificar con esta marca: firebase emulators:start --export-on-exit=./saved-data. Si se usa --import, la ruta de exportación predeterminada es la misma; por ejemplo: firebase emulators:start --import=./data-path --export-on-exit. Por último, si lo prefieres, puedes pasar diferentes rutas de directorio a las marcas --import y --export-on-exit.
--import=IMPORT_DIRECTORY Opcional. Úsalo con el emulador de Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Importa datos guardados con la opción de inicio --export-on-exit o el comando emulators:export a una instancia del emulador de Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase que se esté ejecutando. Se sobrescribirán los datos que haya en la memoria del emulador.
--log-verbosity=VERBOSITY Opcional. Reduce la cantidad de registros de salida de los emuladores para reducir el ruido en la consola y en los archivos de registro. Los valores válidos son DEBUG, INFO, QUIET y SILENT.
emulators:exec PATH/TO/SCRIPT

Ejecuta la secuencia de comandos en PATH/TO/SCRIPT después de iniciar los emuladores de los productos de Firebase configurados en firebase.json. Los procesos del emulador se detendrán automáticamente cuando la secuencia de comandos haya terminado de ejecutarse.

Marcar Descripción
--only Opcional. Limitar qué emuladores se inician. Proporciona una lista separada por comas de nombres de emuladores, especificando uno o varios de los siguientes: firestore, database, functions, hosting o pubsub.
--inspect-functions DEBUG_PORT Opcional. Se usa con el emulador Cloud Functions para habilitar la depuración de puntos de interrupción de funciones en el puerto especificado (o en el puerto predeterminado 9229 si se omite el argumento). Ten en cuenta que, cuando se proporciona esta marca, el emulador de Cloud Functions cambia a un modo de ejecución serializado especial en el que las funciones se ejecutan en un solo proceso, en orden secuencial (por orden de llegada). Esto simplifica la depuración de funciones, aunque el comportamiento difiere de la ejecución paralela de funciones en varios procesos en la nube.
--export-on-exit= Opcional. Úsalo con el emulador de Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Indica a los emuladores que exporten datos a un directorio cuando se produzca un cierre, tal como se describe en el comando emulators:export. El directorio de exportación se puede especificar con esta marca: firebase emulators:start --export-on-exit=./saved-data. Si se usa --import, la ruta de exportación predeterminada es la misma; por ejemplo: firebase emulators:start --import=./data-path --export-on-exit. Por último, si lo prefieres, puedes pasar diferentes rutas de directorio a las marcas --import y --export-on-exit.
--import=IMPORT_DIRECTORY Opcional. Úsalo con el emulador de Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Importa datos guardados con la opción de inicio --export-on-exit o el comando emulators:export a una instancia del emulador de Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase que se esté ejecutando. Se sobrescribirán los datos que haya en la memoria del emulador.
--ui Opcional. Ejecuta la interfaz de usuario del emulador durante la ejecución.
--log-verbosity=VERBOSITY Opcional. Reduce la cantidad de registros de salida de los emuladores para reducir el ruido en la consola y en los archivos de registro. Los valores válidos son DEBUG, INFO, QUIET y SILENT.

El método firebase emulators:exec suele ser más adecuado para los flujos de trabajo de integración continua.

Exportar e importar datos del emulador

Puedes exportar datos de los emuladores de Authentication, Cloud Firestore, Realtime Database y Cloud Storage for Firebase para usarlos como un conjunto de datos de referencia común que se puede compartir. Estos conjuntos de datos se pueden importar con la marca --import, tal como se describe más arriba.

emulators:export export_directory

Emulador de Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Exporta datos de una instancia de emulador de Cloud Firestore, Realtime Database o Cloud Storage for Firebase en ejecución. El export_directory especificado se creará si aún no existe. Si el directorio especificado existe, se te pedirá que confirmes que se deben sobrescribir los datos de exportación anteriores. Puedes saltarte este mensaje con la marca --force. El directorio de exportación contiene un archivo de manifiesto de datos, firebase-export-metadata.json.

Puedes indicar a los emuladores que exporten datos automáticamente cuando se cierren mediante las marcas --export-on-exit descritas anteriormente.

Integración con tu sistema de CI

Ejecutar imágenes de Emulator Suite en contenedores

La instalación y la configuración de la Suite del emulador con contenedores en una configuración de CI típica son sencillas.

Hay algunos problemas que debes tener en cuenta:

  • Los archivos JAR se instalan y se almacenan en caché en ~/.cache/firebase/emulators/.

    • Te recomendamos que añadas esta ruta a la configuración de la caché de CI para evitar descargas repetidas.
  • Si no tienes un archivo firebase.json en tu repositorio, debes añadir un argumento de línea de comandos al comando emulators:start o emulators:exec para especificar qué emuladores deben iniciarse. Por ejemplo,
    --only functions,firestore.

Generar un token de autenticación (solo para el emulador de Hosting)

Si tus flujos de trabajo de integración continua dependen de Firebase Hosting , tendrás que iniciar sesión con un token para ejecutar firebase emulators:exec. Los demás emuladores no requieren inicio de sesión.

Para generar un token, ejecuta firebase login:ci en tu entorno local. No debes hacerlo desde un sistema de CI. Sigue las instrucciones para autenticarte. Solo deberías tener que realizar este paso una vez por proyecto, ya que el token será válido en todas las compilaciones. El token debe tratarse como una contraseña, por lo que debes asegurarte de que se mantenga en secreto.

Si tu entorno de CI te permite especificar variables de entorno que se puedan usar en las secuencias de comandos de compilación, solo tienes que crear una variable de entorno llamada FIREBASE_TOKEN cuyo valor sea la cadena del token de acceso. La CLI de Firebase recogerá automáticamente la variable de entorno FIREBASE_TOKEN y los emuladores se iniciarán correctamente.

Como último recurso, puedes incluir el token en tu secuencia de comandos de compilación, pero asegúrate de que las partes no fiables no tengan acceso. Para usar este enfoque predefinido en el código, puedes añadir --token "YOUR_TOKEN_STRING_HERE" al comando firebase emulators:exec.

Usar la API REST de Emulator Hub

Mostrar emuladores en ejecución

Para ver una lista de los emuladores que se están ejecutando, envía una solicitud GET al endpoint /emulators de Emulator Hub.

curl localhost:4400/emulators

El resultado será un objeto JSON que mostrará todos los emuladores en ejecución y su configuración de host y puerto. Por ejemplo:

{
  "hub":{
    "name": "hub",
    "host": "localhost",
    "port": 4400
  },
  "functions": {
    "name": "functions",
    "host": "localhost",
    "port": 5001
  }
  "firestore": {
    "name": "firestore",
    "host": "localhost",
    "port": 8080
  }
}

Habilitar o inhabilitar activadores de funciones en segundo plano

En algunas situaciones, tendrás que inhabilitar temporalmente los activadores de funciones y extensiones locales. Por ejemplo, puede que quieras eliminar todos los datos del emulador de Cloud Firestore sin activar ninguna función de onDelete que se esté ejecutando en los emuladores de Cloud Functions o Extensions.

Para inhabilitar temporalmente los activadores de funciones locales, envía una solicitud PUT al endpoint /functions/disableBackgroundTriggers del centro de emuladores.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

El resultado será un objeto JSON que detallará el estado actual.

{
  "enabled": false
}

Para habilitar los activadores de funciones locales después de que se hayan inhabilitado, envía una solicitud PUT al endpoint /functions/enableBackgroundTriggers del centro de emuladores.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

El resultado será un objeto JSON que detallará el estado actual.

{
  "enabled": true
}

Integraciones de SDKs de emuladores

En las tablas de esta sección se indican los emuladores que admiten los SDKs de cliente y de administrador. Futuro significa que está previsto que se admita el emulador, pero que aún no está disponible.

Disponibilidad del SDK de cliente

Android Plataformas de Apple Web Firebase UI
Android
Firebase UI
iOS
Firebase UI
Web
Realtime Database 19.4.0 7.2.0 8.0.0 6.4.0 Futuro N/A
Cloud Firestore 21.6.0 7.2.0 8.0.0 6.4.0 Futuro N/A
Authentication 20.0.0 7.0.0 8.0.0 7.0.0 Futuro 4.7.2
Cloud Storage for Firebase 20.0.0 8.0.0 8.4.0 7.0.0 11.0.0 N/A
Cloud Functions 19.1.0 7.2.0 8.0.0 N/A N/A N/A
Hosting N/A N/A N/A N/A N/A N/A
Extensions N/A N/A N/A N/A N/A N/A

Disponibilidad del SDK de administrador

Nodo Java Python Go
Realtime Database 8.6.0 6.10.0 2.18.0 Futuro
Cloud Firestore 8.0.0 6.10.0 3.0.0 1.0.0
Authentication 9.3.0 7.2.0 5.0.0 4.2.0
Cloud Storage for Firebase 9.8.0 Futuro Futuro Futuro
Cloud Functions N/A N/A N/A N/A
Hosting N/A N/A N/A N/A
Extensions N/A N/A N/A N/A