Conectar seu app ao emulador do Cloud Functions

Antes de conectar seu app ao emulador do Cloud Functions, você deve entender o fluxo de trabalho geral do Firebase Local Emulator Suite e instalar e configurar o Local Emulator Suite, além de analisar os comandos da CLI.

Escolher um projeto do Firebase

O Firebase Local Emulator Suite emula produtos para um único projeto do Firebase.

Na CLI, execute firebase use no diretório de trabalho antes de iniciar os emuladores para selecionar o projeto a ser usado. Como opção, é possível transmitir a flag --project para cada comando do emulador.

Local Emulator Suite oferece suporte à emulação de projetos reais do Firebase e projetos de demonstração.

Tipo de projeto Recursos Usar com emuladores
Real

Um projeto real do Firebase é aquele que você criou e configurou (provavelmente pelo console do Firebase).

Os projetos reais têm recursos ativos, como instâncias de banco de dados, buckets de armazenamento, funções ou qualquer outro recurso configurado para o projeto do Firebase.

Ao trabalhar com projetos reais do Firebase, é possível executar emuladores para qualquer um ou todos os produtos suportados.

Para todos os produtos que você não estiver emulando, os apps e o código interagem com recursos ativos, como o banco de dados, o bucket de armazenamento, a função etc.

Demonstração

Um projeto de demonstração do Firebase não tem configuração real nem recursos ativos. Em geral, esses projetos são acessados usando codelabs ou outros tutoriais.

Os IDs dos projetos de demonstração têm o prefixo demo-.

Ao trabalhar com projetos de demonstração do Firebase, os apps e códigos interagem apenas com emuladores. Se o app tentar interagir com um recurso em que um emulador não esteja em execução, o código falhará.

Recomendamos que você use projetos de demonstração sempre que possível. Alguns dos benefícios são:

  • Configuração mais fácil, já que é possível executar os emuladores sem precisar criar um projeto do Firebase
  • Mais segurança, já que, se o código invocar acidentalmente recursos não emulados (produção), não haverá chance de alteração, uso e faturamento de dados
  • Melhor suporte off-line, já que não é necessário acessar a Internet para fazer o download da configuração do SDK

Instruir o app a se comunicar com os emuladores

Instruir o app para funções chamáveis

Se as atividades de teste e protótipo envolverem funções de back-end chamáveis, configure a interação com o emulador de Cloud Functions for Firebase desta forma:

Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val functions = Firebase.functions
functions.useEmulator("10.0.2.2", 5001)
MainActivity.kt
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFunctions functions = FirebaseFunctions.getInstance();
functions.useEmulator("10.0.2.2", 5001);
MainActivity.java
Swift
Functions.functions().useFunctionsEmulator(origin: "http://127.0.0.1:5001")
ViewController.swift

Web

import { getApp } from "firebase/app";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

const functions = getFunctions(getApp());
connectFunctionsEmulator(functions, "127.0.0.1", 5001);
fb_functions_emulator_connect.js

Web

firebase.functions().useEmulator("127.0.0.1", 5001);
emulator-suite.js

Instruir o app para emulação de funções HTTPS

Cada função HTTPS no seu código será disponibilizada pelo emulador local usando o seguinte formato de URL:

http://$HOST:$PORT/$PROJECT/$REGION/$NAME

Por exemplo, uma função helloWorld simples com a porta e a região de host padrão seria disponibilizada em:

https://localhost:5001/$PROJECT/us-central1/helloWorld

Instruir o app para emulação de funções da fila de tarefas

O emulador configura automaticamente as filas de tarefas emuladas com base nas definições do acionador, e o SDK Admin redireciona as solicitações enfileiradas para o emulador se detectar que ele está sendo executado pela variável de ambiente CLOUD_TASKS_EMULATOR_HOST.

O sistema de expedição usado na produção é mais complexo que o implementado no emulador, então não espere que emulados espelhem os ambientes de produção com precisão. Os parâmetros no emulador fornecem limites superiores para a taxa em que as tarefas são despachadas e fazem uma nova tentativa.

Instruir o app para emulação de funções acionadas em segundo plano

O emulador Cloud Functions oferece suporte às funções acionadas em segundo plano das seguintes origens:

  • Emulador de Realtime Database
  • Emulador de Cloud Firestore
  • Emulador de Authentication
  • Emulador de Pub/Sub
  • Emulador de alertas do Firebase

Para acionar eventos em segundo plano, modifique os recursos de back-end usando a IU do Emulator Suite UI. Também é possível conectar seu app ou código de teste aos emuladores usando o SDK da sua plataforma.

Testar manipuladores de eventos personalizados emitidos por Extensões

Em relação às funções implementadas para processar eventos personalizados do Firebase Extensions com o Cloud Functions v2, o emulador do Cloud Functions faz o pareamento com o emulador do Eventarc para oferecer suporte aos gatilhos do Eventarc.

Para testar os manipuladores de eventos personalizados das extensões que emitem eventos, instale os emuladores do Cloud Functions e do Eventarc.

O ambiente de execução Cloud Functions define a variável de ambiente EVENTARC_EMULATORpara localhost:9299 no processo atual se o emulador do Eventarc está em execução. Os Firebase Admin SDKs se conectam automaticamente ao emulador do Eventarc quando a variável de ambiente EVENTARC_EMULATOR está definida. Você pode modificar a porta padrão conforme discutido em Configurar Local Emulator Suite.

Se as variáveis de ambiente são configuradas corretamente, Firebase Admin SDK envia eventos automaticamente para o emulador do Eventarc. Por sua vez, o emulador de Eventarc faz um callback para o emulador de Cloud Functions para acionar quaisquer gerenciadores registrados.

Consulte os registros do Functions no Emulator Suite UI para ver detalhes sobre a execução do gerenciador.

Configurar um ambiente de teste local

Se as funções dependem da configuração de ambiente baseada em dotenv, é possível emular esse comportamento no ambiente de teste local.

Ao usar um emulador local do Cloud Functions, é possível modificar as variáveis de ambiente para o projeto configurando um arquivo .env.local. O conteúdo de .env.local tem precedência sobre .env e sobre o arquivo .env específico do projeto.

Por exemplo, um projeto pode incluir esses três arquivos com valores um pouco diferentes para desenvolvimento e teste local:

.env .env.dev .env.local
PLANET=Earth

AUDIENCE=Humans

AUDIENCE=Dev Humans AUDIENCE=Local Humans

Quando iniciado no contexto local, o emulador carrega as variáveis de ambiente da seguinte maneira:

  $ firebase emulators:start
  i  emulators: Starting emulators: functions
  # Starts emulator with following environment variables:
  #  PLANET=Earth
  #  AUDIENCE=Local Humans

Secrets e credenciais no emulador de Cloud Functions

O emulador de Cloud Functions é compatível com o uso de secrets para armazenar e acessar informações sensíveis de configuração. Por padrão, o emulador tentará acessar seus secrets de produção usando credenciais padrão do aplicativo. Em determinadas situações, como ambientes de CI, o emulador pode não acessar valores do secret por causa de restrições de permissão.

Da mesma forma que o suporte do emulador Cloud Functions para variáveis de ambiente, é possível substituir valores de segredos configurando um arquivo .secret.local. Isso facilita o teste local das funções, especialmente se você não tiver acesso ao valor do secret.

Quais outras ferramentas para testar Cloud Functions existem?

O pacote do emulador de Cloud Functions é complementado por outras ferramentas de prototipagem e testes:

  • O shell do Cloud Functions, que permite o desenvolvimento e a prototipagem de funções interativos e iterativos. O shell emprega o emulador do Cloud Functions com uma interface no estilo REPL para desenvolvimento. Nenhuma integração com os emuladores Cloud Firestore ou Realtime Database é fornecida. Usando o shell, simular dados e realizar chamadas de função para simular a interação com produtos que o Local Emulator Suite não oferece suporte atualmente: Analytics, Configuração remota e Crashlytics.
  • O SDK de teste do Firebase para Cloud Functions, um Node.js com framework mocha para desenvolvimento de funções. Na verdade, o SDK de teste do Cloud Functions fornece automação sobre o shell do Cloud Functions.

Saiba mais sobre o shell do Cloud Functions e o SDK de teste do Cloud Functions em Testar funções interativamente e Teste de unidade do Cloud Functions.

Qual é a diferença entre o emulador do Cloud Functions e a produção?

O emulador Cloud Functions é bastante próximo do ambiente de produção na maioria dos casos de uso. Fizemos todo o trabalho para garantir que tudo dentro do ambiente de execução do Node esteja o mais próximo possível da produção. No entanto, o emulador não imita o ambiente de produção conteinerizado completo. Dessa forma, embora o código da função seja executado de maneira realista, outros aspectos do ambiente podem ser diferentes, como arquivos locais, comportamento após falhas e assim por diante.

Cloud IAM

O Pacote do emuladores do Firebase não tenta replicar nem respeitar qualquer comportamento relacionado ao IAM para execução. Os emuladores aderem às regras de segurança do Firebase fornecidas, mas em situações em que o IAM normalmente seria usado, por exemplo, para definir o Cloud Functions que invoca a conta de serviço e as permissões, o emulador não é configurável e usará a conta disponível globalmente na máquina de desenvolvimento, semelhante à execução direta de um script local.

Restrições de memória e processador

O emulador não impõe restrições de memória ou processador às funções. No entanto, o emulador suporta o tempo limite das funções. Para isso, ele usa o argumento timeoutSeconds do ambiente de execução.

O tempo de execução da função pode ser diferente da produção quando as funções são executadas no emulador. Depois de projetar e testar funções com o emulador, é recomendável executar testes limitados em produção para confirmar os tempos de execução.

Como planejar diferenças em ambientes locais e de produção

Como o emulador é executado na máquina local, ele depende do ambiente local para aplicativos, utilitários e programas integrados.

O ambiente local para o desenvolvimento de Cloud Functions pode ser diferente do ambiente de produção do Google:

  • Os aplicativos instalados localmente para simular o ambiente de produção (por exemplo, o ImageMagick deste tutorial) podem ter o comportamento diferente se comparados à produção, especialmente se você precisar de versões diferentes ou desenvolver em um ambiente não Linux. Considere implantar sua própria cópia binária do programa ausente junto da implantação da função.

  • Da mesma forma, os utilitários integrados (por exemplo, comandos do shell como ls e mkdir) podem ser diferentes das versões disponíveis em produção, especialmente se você estiver desenvolvendo em um ambiente que não é Linux (por exemplo, macOS). Para lidar com esse problema, use alternativas exclusivas do Node.js para comandos nativos ou crie binários do Linux para incluir na sua implantação.

Tentando novamente

O emulador do Cloud Functions não suporta a repetição de funções em caso de falha.

A seguir