Join us for Firebase Summit on November 10, 2021. Tune in to learn how Firebase can help you accelerate app development, release with confidence, and scale with ease. Register

Instalar, configurar e integrar o Pacote do emulador local

O Pacote do emulador local do Firebase pode ser instalado e configurado para diferentes ambientes de protótipo e teste, desde sessões de prototipagem únicas até fluxos de trabalho de integração contínua em escala de produção.

Instalar o Pacote do emulador local

Antes de instalar o Pacote do emulador, você precisará de:

  • Node.js versão 8.0 ou superior
  • Java versão 1.8 ou superior

Para instalar o Pacote do emulador:

  1. Instale a CLI do Firebase. Se você ainda não instalou a CLI do Firebase, faça a instalação agora mesmo. Você precisará da CLI versão 8.14.0 ou posterior para usar o conjunto de emuladores. É possível verificar qual versão está instalada usando o seguinte comando:
    firebase --version
  2. Se ainda não tiver feito isso, inicialize o diretório de trabalho atual como um projeto do Firebase, seguindo as instruções na tela para especificar quais produtos usar:
    firebase init
  3. Configure o Pacote do emulador. Este comando inicia um assistente de configuração que permite selecionar emuladores do seu interesse, fazer o download dos arquivos binários do emulador correspondentes e definir as portas do emulador se os padrões não forem apropriados.
    firebase init emulators

Depois que um emulador for instalado, nenhuma verificação de atualização será realizada e nenhum download automático adicional ocorrerá até que você atualize a versão da CLI do Firebase.

Configurar o Pacote do emulador

Como opção, você pode configurar as portas de rede dos emuladores e o caminho para as definições de regras de segurança no arquivo firebase.json:

  • Altere as portas do emulador executando firebase init emulators ou editando firebase.json manualmente.
  • Altere o caminho para as definições de regras de segurança editando firebase.json manualmente.

Se você não definir essas configurações, os emuladores ouvirão nas portas padrão, e os emuladores do Cloud Firestore, Realtime Database e Cloud Storage serão executados com segurança de dados aberta.

Comando Descrição
emuladores init Inicie um assistente de inicialização do emulador. Identifique os emuladores a serem instalados e, opcionalmente, especifique as configurações da porta do emulador. init emulators não é destrutivo; se você aceitar os padrões, a configuração atual do emulador será preservada.

Configuração da porta

Cada emulador é vinculado a uma porta diferente na sua máquina com um valor padrão preferido.

Emulador Porta padrão
Authentication 9099
IU do Pacote do Emulador 4000
Cloud Functions 5001
Realtime Database 9000
Cloud Firestore 8080
Cloud Storage 9199
Firebase Hosting 5000
Pub/Sub 8085

Configuração das regras de segurança

Os emuladores utilizarão a configuração das regras de segurança das chaves de configuração database, firestore e storage em 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": {
    "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"
    }
  }
}

Iniciar emuladores

É possível iniciar os emuladores para serem executados até serem encerrados manualmente ou para serem executados durante um script de teste designado e depois encerrados automaticamente.

Comando Descrição
emulators:start Inicie emuladores para os produtos do Firebase configurados em firebase.json. Os processos do emulador continuarão em execução até serem explicitamente interrompidos. Chame emulators:start para fazer o download dos emuladores em ~/.cache/firebase/emulators/ se eles ainda não estiverem instalados.
Sinalização Descrição
--only Opcional. Limite quais emuladores serão iniciados. Forneça uma lista separada por vírgulas de nomes de emulador, especificando um ou mais de "auth", "database", "firestore", "functions", "hosting" ou "pubsub".
--inspect-functions debug_port Opcional. Use com o emulador do Cloud Functions para ativar a depuração de ponto de interrupção de funções na porta especificada (ou a porta padrão 9229 se o argumento for omitido). Observe que, quando essa sinalização é fornecida, o emulador do Cloud Functions alterna para um modo de execução serializado especial em que as funções são executadas em um único processo, em ordem sequencial (FIFO, na sigla em inglês). Isso simplifica a depuração de funções, embora o comportamento seja diferente da execução paralela de vários processos na nuvem.
--export-on-exit= Opcional. Use com o emulador do Authentication, Cloud Firestore, Realtime Database ou Cloud Storage. Instrua os emuladores a exportar dados para um relatório quando a interrupção ocorrer, conforme descrito para o comando emulators:export. O diretório de exportação pode ser especificado com esta sinalização: firebase emulators:start --export-on-exit=./saved-data. Se --import for usado, o caminho de exportação será o mesmo, por exemplo: firebase emulators:start --import=./data-path --export-on-exit. Por fim, é possível transmitir caminhos de diretório diferentes para as sinalizações --import e --export-on-exit.
--import=import_directory Opcional. Use com o emulador do Authentication, Cloud Firestore, Realtime Database ou Cloud Storage. Importe dados salvos usando a opção de inicialização --export-on-exit ou o comando emulators:export para uma instância de emulador em execução do Authentication, Cloud Firestore, Realtime Database ou Cloud Storage. Todos os dados atualmente na memória do emulador serão substituídos.
emulators:exec scriptpath Execute o script em scriptpath depois de iniciar emuladores para os produtos do Firebase configurados em firebase.json. Os processos do emulador serão interrompidos automaticamente quando a execução do script for concluída.
Sinalização Descrição
--only Opcional. Limite quais emuladores serão iniciados. Forneça uma lista separada por vírgulas de nomes de emulador, especificando um ou mais de "firestore", "database", "functions", "host" ou "pubsub".
--inspect-functions debug_port Opcional. Use com o emulador do Cloud Functions para ativar a depuração de ponto de interrupção de funções na porta especificada (ou a porta padrão 9229 se o argumento for omitido). Observe que, quando essa sinalização é fornecida, o emulador do Cloud Functions alterna para um modo de execução serializado especial em que as funções são executadas em um único processo, em ordem sequencial (FIFO, na sigla em inglês). Isso simplifica a depuração de funções, embora o comportamento seja diferente da execução paralela de vários processos na nuvem.
--export-on-exit= Opcional. Use com o emulador do Authentication, Cloud Firestore, Realtime Database ou Cloud Storage. Instrua os emuladores a exportar dados para um relatório quando a interrupção ocorrer, conforme descrito para o comando emulators:export. O diretório de exportação pode ser especificado com esta sinalização: firebase emulators:start --export-on-exit=./saved-data. Se --import for usado, o caminho de exportação será o mesmo, por exemplo: firebase emulators:start --import=./data-path --export-on-exit. Por fim, é possível transmitir caminhos de diretório diferentes para as sinalizações --import e --export-on-exit.
--import=import_directory Opcional. Use com o emulador do Authentication, Cloud Firestore, Realtime Database ou Cloud Storage. Importe dados salvos usando a opção de inicialização --export-on-exit ou o comando emulators:export para uma instância de emulador em execução do Authentication, Cloud Firestore, Realtime Database ou Cloud Storage. Todos os dados atualmente na memória do emulador serão substituídos.
--ui Opcional. Execute a IU do emulador durante a execução.

O método firebase emulators:exec geralmente é mais apropriado para fluxos de trabalho de integração contínua.

Exportar e importar dados do emulador

É possível exportar dados dos emuladores do Authentication, Cloud Firestore, Realtime Database e Cloud Storage para usar como um conjunto de dados de referência comum compartilhável. Esses conjuntos de dados podem ser importados usando a sinalização --import, conforme descrito acima.

emulators:export export_directory

Emulador do Authentication, Cloud Firestore, Realtime Database ou Cloud Storage. Exportar dados de uma instância de emulador do Cloud Firestore, Realtime Database ou Cloud Storage em execução. O export_directory especificado será criado se ainda não existir. Se o diretório especificado existir, você deverá confirmar que os dados de exportação anteriores devem ser substituídos. É possível ignorar esse prompt usando a sinalização --force. O diretório de exportação contém um arquivo de manifesto de dados, firebase-export-metadata.json.

Instrua os emuladores a exportar dados automaticamente quando forem desligados usando as sinalizações --export-on-exit descritas acima.

Integrar com o sistema de CI

Como executar imagens do Pacote do emulador em contêiner

A instalação e a configuração do Pacote do emulador com contêineres em uma configuração de CI típica são simples.

Fique atento a alguns problemas:

  • Os arquivos JAR são instalados e armazenados em cache em ~/.cache/firebase/emulators/.

    • Adicione esse caminho à configuração do cache de CI para evitar downloads repetidos.
  • Se você não tiver um arquivo firebase.json no seu repositório, adicione um argumento de linha de comando ao comando emulators:start ou emulators:exec para especificar quais emuladores devem ser iniciados. Por exemplo,
    --only functions,firestore.

Gerar um token de autenticação (somente emulador do Hosting)

Se os fluxos de trabalho de integração contínua dependerem do Firebase Hosting, você precisará fazer login usando um token para executar firebase emulators:exec. Os outros emuladores não exigem login.

Para gerar um token, execute firebase login:ci no ambiente local. Isso não deve ser realizado em um sistema de CI. Siga as instruções para fazer a autenticação. Você só precisa executar essa etapa uma vez por projeto, já que o token será válido entre os builds. O token deve ser tratado como uma senha. Mantenha-o em segredo.

Se o ambiente de CI permitir que você especifique variáveis de ambiente que podem ser usadas nos scripts de compilação, basta criar uma variável de ambiente chamada FIREBASE_TOKEN, com o valor sendo a string do token de acesso. A CLI do Firebase selecionará automaticamente a variável de ambiente FIREBASE_TOKEN, e os emuladores serão iniciados corretamente.

Como último recurso, você pode simplesmente incluir o token no script de compilação, mas certifique-se de que as partes não confiáveis não tenham acesso. Para essa abordagem codificada, adicione --token "YOUR_TOKEN_STRING_HERE" ao comando firebase emulators:exec.

Usar a API REST do emulador Hub

Listar emuladores em execução

Para listar os emuladores em execução no momento, envie uma solicitação GET ao endpoint /emulators do emulador Hub.

curl localhost:4400/emulators

O resultado será um objeto JSON listando todos os emuladores em execução e a configuração de host/porta deles, por exemplo:

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

Ativar / desativar acionadores de funções de segundo plano

Em algumas situações, será necessário desativar temporariamente os acionadores de funções locais. Por exemplo, talvez você queira excluir todos os dados no emulador do Cloud Firestore sem acionar qualquer função onDelete em execução no emulador do Cloud Functions.

Para desativar temporariamente os gatilhos de funções locais, envie uma solicitação PUT ao endpoint /functions/disableBackgroundTriggers do emulador Hub.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

O resultado será um objeto JSON detalhando o estado atual.

{
  "enabled": false
}

Para ativar os acionadores de funções locais depois da desativação, envie uma solicitação PUT para o endpoint /functions/enableBackgroundTriggers do Hub do emulador.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

O resultado será um objeto JSON detalhando o estado atual.

{
  "enabled": true
}

Integrações do SDK do emulador

As tabelas nesta seção indicam quais emuladores são compatíveis com SDKs de cliente e administrador. Futuro significa que a compatibilidade com o emulador está planejada, mas ainda não está disponível.

Disponibilidade do SDK do cliente

Android iOS Web IU do Firebase
Android
IU do Firebase
iOS
IU do 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 Futuro
Cloud Storage 20.0.0 8.0.0 8.4.0 N/A N/A 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

Disponibilidade do SDK Admin

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 Futuro Futuro Futuro
Cloud Storage 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