Instalar, configurar e integrar la Suite del Emulador Local

El conjunto de herramientas del emulador local de Firebase se puede instalar y configurar para diferentes entornos de prototipos y pruebas, desde sesiones de creación de prototipos puntuales hasta flujos de trabajo de integración continua a escala de producción.

Instalar la Suite del emulador local

Antes de instalar Suite del emulador, necesitarás lo siguiente:

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

Para instalar Suite del emulador, sigue estos pasos:

1. Instala la CLI de Firebase. Si aún no has instalado la CLI de Firebase, instálala ahora. Para usar la Suite del emulador, necesitas la versión 8.14.0 o una posterior de la CLI. 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 proyecto de Firebase. Para ello, sigue las indicaciones que aparecen en pantalla para especificar qué productos quieres usar:

   firebase init

3. Configura la Suite del emulador. Este comando inicia un asistente de configuración que te permite seleccionar los emuladores que te interesan, descargar los archivos binarios correspondientes y definir los puertos de los emuladores si los predeterminados no son adecuados.

   firebase init emulators

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

Configurar Suite del emulador

También puedes configurar los puertos de red de los emuladores y la ruta a las definiciones de reglas de seguridad en el archivo firebase.json:

• Para cambiar los puertos del emulador, ejecuta firebase init emulators o edita firebase.json manualmente.
• Cambia la ruta a las definiciones de reglas de seguridad editando firebase.json manualmente.

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

Configuración de puertos

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

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 concreto. En estos casos, las instancias de emulador se ejecutan en un entorno independiente.

Por lo general, es recomendable definir un ID de proyecto para todas las invocaciones del emulador, de modo que Emulator Suite UI, los diferentes emuladores de 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 los siguientes casos:

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

También debes comprobar 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 Realtime Database, el emulador Cloud Firestore y parte del emulador 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 tienes errores relacionados con el espacio de montículo de Java, puedes aumentar el tamaño máximo del montículo 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 interfaz de línea de comandos Firebase, como Emulator Suite UI.

Iniciar emuladores

Puedes iniciar emuladores para que se ejecuten hasta que se cierren manualmente o para que se ejecuten durante la duración de un script de prueba designado y, a continuación, se cierren automáticamente.

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

Exportar e importar los datos del emulador

Puedes exportar datos de los emuladores Authentication, Cloud Firestore, Realtime Database y Cloud Storage for Firebase para usarlos como conjunto de datos de referencia común y compartible. Estos conjuntos de datos se pueden importar con la marca --import, tal como se ha descrito anteriormente.

Integrar con tu sistema de CI

Ejecutar imágenes de Emulator Suite en contenedores

La instalación y configuración de Suite del emulador con contenedores en una configuración de integración continua típica es sencilla.

Hay algunos aspectos que debes tener en cuenta:

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

  • Puede que quieras añadir esta ruta a la configuración de la caché de integración continua 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 se deben iniciar. 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 otros emuladores no requieren que inicies sesión.

Para generar un token, ejecuta firebase login:ci en tu entorno local. No debes hacerlo desde un sistema de integración continua. Sigue las instrucciones para autenticarte. Solo tendrá 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, así que asegúrate de que siga siendo secreto.

Si tu entorno de integración continua 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 detectará 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 terceros no fiables no tengan acceso. Para este enfoque codificado, 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 enumerar los emuladores que se están ejecutando, envía una solicitud GET al endpoint /emulators del centro de emuladores.

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 algunos casos, tendrás que inhabilitar temporalmente la función local y los activadores de extensiones. Por ejemplo, puede que quieras eliminar todos los datos del emulador Cloud Firestore sin activar ninguna función onDelete que se esté ejecutando en los emuladores Cloud Functions o Extensions.

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

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

El resultado será un objeto JSON con información detallada sobre 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 de Emulator Hub.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

El resultado será un objeto JSON con información detallada sobre el estado actual.

{
  "enabled": true
}

Integraciones de SDKs de emulador

Las tablas de esta sección indican qué emuladores son compatibles con los SDKs de cliente y de administrador. Futuro significa que se ha previsto la compatibilidad con emuladores, pero aún no está disponible.

Disponibilidad del SDK de cliente

Disponibilidad del SDK Admin