Usar o emulador de extensões para avaliar extensões

Antes de usar o emulador de Extensions com seu app, certifique-se de entender o fluxo de trabalho geral do Firebase Local Emulator Suite, instalar e configurar o Local Emulator Suite e revisar os comandos da CLI.

Para acompanhar este guia, você também precisa conhecer o Firebase Extensions e seu uso nos apps do Firebase.

O que posso fazer com o emulador de Extensions?

Com o emulador de Extensions, é possível instalar e gerenciar extensões em um ambiente local seguro, além de entender melhor os recursos delas, o que ajuda a minimizar os custos faturados. O emulador executa as funções da extensão localmente, incluindo as acionadas por eventos em segundo plano usando os emuladores do Cloud Firestore, Realtime Database, Cloud Storage for Firebase, Authentication e Pub/Sub, além das funções acionadas pelo Eventarc implementadas no Cloud Functions v2.

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

Instalar e avaliar uma extensão

É fácil usar o emulador de Extensions para avaliar se uma extensão atende às suas necessidades.

Vamos supor que você tenha interesse na extensão do e-mail de gatilho (firestore-send-email), mesmo que o fluxo de trabalho a seguir aceite qualquer extensão. Quando executado com emuladores locais, o e-mail de acionamento vai usar automaticamente os emuladores de Cloud Firestore e Cloud Functions.

Para avaliar uma extensão localmente:

  1. Adicione a extensão ao manifesto de extensões locais. Um manifesto de extensões é uma lista de instâncias de extensões e suas configurações.

    firebase ext:install --local firebase/firestore-send-email

    Com a execução do comando acima, você vai precisar configurar a versão mais recente da extensão firebase/firestore-send-email e salvar a configuração no manifesto, mas a execução não vai implantar a configuração no projeto. Para saber mais, consulte Gerenciar a configuração de extensões com manifestos.

  2. Inicie o Local Emulator Suite normalmente.

    firebase emulators:start

Agora, usando a instância de extensão firestore-send-email listada no manifesto, o Local Emulator Suite vai fazer o download do código-fonte dessa extensão para ~/.cache/firebase/extensions. Depois do download do código-fonte, o Local Emulator Suite será iniciado e será possível acionar qualquer uma das funções acionadas em segundo plano da extensão e conectar seu app ao Local Emulator Suite para testar a integração.

Você pode usar Emulator Suite UI para adicionar dados à coleção de documentos de e-mail e configurar outros recursos de back-end, conforme exigido pela extensão do acionador de e-mail.

Como alternativa, para ambientes de teste não interativos, como fluxos de trabalho de integração contínua, é possível escrever um script de teste para avaliar a extensão que, entre outras etapas, preenche os dados necessários do Cloud Firestore e aciona funções. Em seguida, você poderia invocar o Local Emulator Suite para executar seu script de teste:

firebase emulators:exec my-test.sh

Qual é a diferença entre o teste com o emulador do Extensions e a produção?

Com o emulador do Extensions, é possível testar extensões de maneira semelhante à experiência de produção. No entanto, existem algumas diferenças em relação ao comportamento de produção.

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. Porém, 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 vai usar a conta disponível globalmente na máquina de desenvolvimento, semelhante à execução direta de um script local.

Limitação de tipo de acionador

No momento, Firebase Local Emulator Suite só oferece suporte a funções acionadas por solicitações HTTP, gatilhos de eventos personalizados do Eventarc para extensões e funções acionadas por eventos em segundo plano para Cloud Firestore, Realtime Database, Cloud Storage for Firebase, Authentication e Pub/Sub. Para avaliar as extensões que usam outros tipos de funções acionadas, é necessário instalar sua extensão em um projeto de teste do Firebase.

A seguir