Instala, configura e integra Local Emulator Suite

Firebase Local Emulator Suite se puede instalar y configurar para diferentes entornos de prototipado y realización de pruebas. Esto incluye desde sesiones únicas de creación de prototipos hasta flujos de trabajo de integración continua a escala de producción.

Instala Local Emulator Suite

Antes de instalar Emulator Suite, necesitarás lo siguiente:

  • Node.js (versión 16.0 o una posterior)
  • Java Development Kit (JDK) 11 o una versión posterior

Sigue estas instrucciones para instalar Emulator Suite:

  1. Instala la CLI de Firebase. Si aún no lo has hecho, instálala ahora. Necesitarás la versión 8.14.0 o una posterior para usar Emulator Suite. Ejecuta el siguiente comando para verificar la versión que tienes instalada: 
    firebase --version
  2. Si aún no lo has hecho, inicializa el directorio de trabajo actual como un proyecto de Firebase y sigue las indicaciones en pantalla para especificar los productos que usarás: 
    firebase init
  3. Configura Emulator Suite. Este comando inicia un asistente de configuración que te permite seleccionar emuladores de interés, descargar los archivos binarios correspondientes del emulador y establecer puertos para el emulador si los valores predeterminados no son adecuados. 
    firebase init emulators

Una vez que se instale un emulador, no se realizarán verificaciones de actualizaciones ni descargas automáticas adicionales hasta que actualices la versión de Firebase CLI.

Configura Emulator Suite

De forma opcional, puedes configurar los puertos de red y la ruta de acceso de los emuladores a las definiciones de las reglas de seguridad en el archivo firebase.json:

  • Ejecuta firebase init emulators o edita firebase.json de forma manual para cambiar los puertos del emulador.
  • Edita firebase.json manualmente para cambiar la ruta de acceso a las definiciones de las reglas de seguridad.

Si no estableces estos parámetros de configuración, 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 datos abierta.

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

Configuración de puertos

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

Emulador Puerto predeterminado
Authentication 9099
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 del proyecto

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

Por lo general, se recomienda configurar un ID del proyecto para todas las invocaciones del emulador para que la Emulator Suite UI, los distintos emuladores de productos y todas las instancias en ejecución de un emulador particular se comuniquen correctamente en todos los casos.

El Local Emulator Suite emite advertencias cuando detecta múltiples IDs de proyectos en el entorno, aunque puedes anular este comportamiento si configuras la clave singleProjectMode como false en tu firebase.json.

Puedes verificar las discrepancias de las declaraciones de los IDs de proyectos en los siguientes casos:

  • El proyecto predeterminado en la línea de comandos. De forma predeterminada, el ID del proyecto se tomará en el inicio del proyecto seleccionado con firebase init o firebase use. Para ver la lista de proyectos (y ver cuál está seleccionado), usa firebase projects:list.
  • En pruebas de unidades de reglas. El ID del proyecto a menudo se especifica en las llamadas a los métodos initializeTestEnvironment o initializeTestApp de la biblioteca de pruebas de unidades de reglas.
  • La marca --project de la línea de comandos. Pasar la marca --project de Firebase CLI anula el proyecto predeterminado. Deberás asegurarte de que el valor de la marca coincida con el ID del proyecto en las pruebas de unidades y la inicialización de la app.

Verifica también las configuraciones de ID del proyecto específicas de la plataforma que estableciste cuando configuraste tus proyectos de plataformas de Apple, Android y la Web.

Configuración de reglas de seguridad

Los emuladores obtendrán la configuración de las reglas de seguridad de las claves de configuración database, firestore y storage en 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"
    }
  }
}

Especifica las opciones de Java

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

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

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

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

Inicia los emuladores

Puedes iniciar los emuladores para que se ejecuten hasta que se cierren de forma manual o para que se ejecuten durante una secuencia de comandos de prueba designada y se cierren automáticamente.

Comando Descripción
emulators:start Inicia los emuladores de productos de Firebase que se configuraron en firebase.json. Los procesos del emulador seguirán ejecutándose hasta que se detengan de forma explícita. Si se llama a emulators:start, los emuladores se descargarán en ~/.cache/firebase/emulators/ si aún no se instalaron.
Marcar Descripción
--only Opcional. Limita los emuladores que se inician. Proporciona una lista de nombres de emuladores separada por comas, en la que se especifiquen una o más entradas de “auth”, “database”, “firestore”, “functions”, “hosting” o “pubsub”.
--inspect-functions debug_port Opcional. Se utiliza con el emulador de Cloud Functions para habilitar la depuración de puntos de interrupción de las funciones en un puerto específico (o el puerto predeterminado 9229 si se omite el argumento). Cuando esta marca se proporciona, el emulador de Cloud Functions cambia a un modo especial de ejecución serializada en el que las funciones se ejecutan en un solo proceso, en orden secuencial (FIFO). Esto simplifica la depuración de funciones, aunque el comportamiento difiere de la ejecución paralela de varios procesos de funciones en la nube.
--export-on-exit= Opcional. Se usa 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 el cierre, como se describe en el comando emulators:export. El directorio de exportación se puede especificar con la marca firebase emulators:start --export-on-exit=./saved-data. Si se usa --import, la ruta de exportación predeterminada es igual. Por ejemplo: firebase emulators:start --import=./data-path --export-on-exit. Por último, si lo deseas, pasa diferentes rutas de directorio a las marcas --import y --export-on-exit.
--import=import_directory Opcional. Se usa con el emulador de Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Importa los datos guardados con la opción de inicio --export-on-exit o el comando emulators:export a una instancia en ejecución del emulador de Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Se reemplazarán todos los datos que se encuentren en la memoria del emulador.
emulators:exec scriptpath Ejecuta la secuencia de comandos ubicada en scriptpath después de iniciar los emuladores de los productos de Firebase que se configuraron 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. Limita los emuladores que se inician. Proporciona una lista de nombres de emuladores separada por comas, en la que se especifican una o más entradas de “firestore”, “database”, “functions”, “hosting” o “pubsub”.
--inspect-functions debug_port Opcional. Se utiliza con el emulador de Cloud Functions para habilitar la depuración de puntos de interrupción de las funciones en un puerto específico (o el puerto predeterminado 9229 si se omite el argumento). Recuerda que cuando se proporciona esta marca, el emulador de Cloud Functions cambia a un modo especial de ejecución serializada en el que las funciones se ejecutan en un solo proceso y en orden secuencial (FIFO). Esto simplifica la depuración de funciones, aunque el comportamiento difiere de la ejecución paralela y de varios procesos de las funciones en la nube.
--export-on-exit= Opcional. Se usa 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 el cierre, como se describe en el comando emulators:export. El directorio de exportación se puede especificar con la marca firebase emulators:start --export-on-exit=./saved-data. Si se usa --import, la ruta de exportación predeterminada es igual. Por ejemplo: firebase emulators:start --import=./data-path --export-on-exit. Por último, si lo deseas, pasa diferentes rutas de directorio a las marcas --import y --export-on-exit.
--import=import_directory Opcional. Se usa con el emulador de Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Importa los datos guardados con la opción de inicio --export-on-exit o el comando emulators:export a una instancia en ejecución del emulador de Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Se reemplazarán todos los datos que se encuentren en la memoria del emulador.
--ui Opcional. Ejecuta la IU del emulador durante la ejecución.

Por lo general, el método firebase emulators:exec es más apropiado para los flujos de trabajo de integración continua.

Importa y exporta datos de emulador

Puedes exportar datos de los emuladores de Authentication, Cloud Firestore, Realtime Database y Cloud Storage for Firebase para usar como conjunto de datos de referencia común que se pueden compartir. Estos conjuntos de datos pueden importarse con la marca --import, como se describió anteriormente.

emulators:export export_directory

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

Con las marcas --export-on-exit descritas anteriormente, puedes indicarles a los emuladores que exporten datos de forma automática cuando se cierren.

Integra en tu sistema de CI

Ejecuta imágenes de Emulator Suite en contenedores

La instalación y configuración de Emulator Suite con contenedores en un entorno típico de CI es sencilla.

Estos son algunos problemas que debes tener en cuenta:

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

    • Recomendamos agregar esta ruta de acceso a la configuración de caché de la CI para evitar que se repitan las descargas.

  • Si no tienes un archivo firebase.json en tu repositorio, debes agregar un argumento de línea de comandos a los comandos emulators:start o emulators:exec para especificar los emuladores que se deben iniciar. Por ejemplo,
    --only functions,firestore.

Genera un token de autenticación (solo en el emulador de Hosting)

Si tus flujos de trabajo de integración continua dependen de Firebase Hosting, deberás acceder con un token para ejecutar firebase emulators:exec. Los otros emuladores no requieren acceso.

Para generar un token, ejecuta firebase login:ci en tu entorno local. Esta acción no debe realizarse desde un sistema de CI. Sigue las instrucciones para realizar la autenticación. Puesto que el token será válido en todas las versiones, solo debes realizar este paso una vez por proyecto. El token se debe tratar como si fuera una contraseña, así que asegúrate de mantenerlo en secreto.

Si el entorno de CI te permite especificar variables de entorno que se pueden usar en las secuencias de comandos de la versión, solo crea una variable de entorno que se llame FIREBASE_TOKEN y que el valor sea la cadena del token de acceso. Firebase CLI detectará automáticamente la variable de entorno FIREBASE_TOKEN y los emuladores se iniciarán de forma correcta.

Como último recurso, puedes incluir el token en tu secuencia de comandos de compilación, pero asegúrate de que los terceros no confiables no tengan acceso. Para este enfoque hard-coded, puedes agregar --token "YOUR_TOKEN_STRING_HERE" al comando firebase emulators:exec.

Usa la API de REST de Emulator Hub

Obtén una lista de los emuladores en ejecución

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

curl localhost:4400/emulators

El resultado será un objeto JSON que muestra todos los emuladores en ejecución, como también 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
  }
}

Habilita o inhabilita activadores de funciones en segundo plano

En algunas situaciones, deberás inhabilitar temporalmente la función local y los activadores de extensiones. Por ejemplo, es posible que quieras borrar todos los datos del emulador de Cloud Firestore sin activar ninguna función onDelete que se ejecute en los emuladores de Cloud Functions o de Extensions.

Para inhabilitar temporalmente los activadores de funciones locales, envía una solicitud PUT al extremo /functions/disableBackgroundTriggers de Emulator Hub.

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 extremo /functions/enableBackgroundTriggers de Emulator Hub.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

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

{
  "enabled": true
}

Integraciones del SDK del emulador

Las tablas de esta sección indican qué emuladores son compatibles con los SDK cliente y de Admin. Futuro significa que la compatibilidad con el emulador está planificada, pero aún no se encuentra disponible.

Disponibilidad del SDK cliente

Android Plataformas de Apple Web IU de Firebase
Android 		IU de Firebase
iOS 		IU de Firebase
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 Admin

Node 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