Conectar seu app ao emulador do Cloud Functions

Antes de conectar seu app ao emulador do Cloud Functions, você precisa entender o fluxo de trabalho geral do Pacote de emuladores locais do Firebase, além de instalar e configurar esse pacote e conferir os comandos da CLI.

Escolher um projeto do Firebase

O Pacote de emuladores locais do Firebase emula produtos para um único projeto.

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.

O Pacote de emuladores locais oferece suporte à emulação de projetos reais e de demonstração do Firebase.

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 do Cloud Functions para Firebase da seguinte maneira:

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 acionadas em segundo plano

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

  • Emulador do Realtime Database
  • Emulador do Cloud Firestore
  • Emulador do Authentication
  • Emulador do Pub/Sub

Para acionar eventos em segundo plano, modifique os recursos de back-end usando a IU do Pacote de emuladores. 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 das Extensões do Firebase 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 do Cloud Functions vai definir a variável de ambiente EVENTARC_EMULATOR como localhost:9299 no processo atual se o emulador do Eventarc estiver em execução. Os SDKs Admin do Firebase se conectam automaticamente ao emulador do Eventarc quando a variável de ambiente EVENTARC_EMULATOR está definida. É possível modificar a porta padrão conforme descrito em Configurar o Pacote de emuladores locais.

Quando as variáveis de ambiente são configuradas corretamente, o SDK Admin do Firebase envia eventos automaticamente para o emulador do Eventarc, que faz um retorno de chamada ao emulador do Cloud Functions para acionar todos os manipuladores registrados.

É possível verificar os registros do Functions na IU do Pacote de emuladores para ver detalhes sobre a execução do manipulador.

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 do Cloud Functions

O emulador do Cloud Functions suporta o uso de secrets para armazenar e acessar informações de configuração confidenciais. 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 emulador do Cloud Functions suporta variáveis de ambiente, é possível substituir valores de secrets configurando um arquivo .secret.local. Isso facilita o teste local das funções, especialmente se você não tiver acesso ao valor do secret.

Existem outras ferramentas para testar o Cloud Functions?

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

  • 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 do Cloud Firestore ou do Realtime Database é fornecida. Com o shell, você simula dados e faz chamadas de função para simular a interação com produtos sem suporte no Pacote de emuladores locais: 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 do Cloud Functions é razoavelmente semelhante ao 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 do 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.

Novas tentativas

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

A seguir