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

Antes de usar o emulador do recurso Extensões com o app, confira o fluxo de trabalho geral do Pacote de emuladores locais do Firebase e instale e configure esse conjunto. Além disso, confira os comandos da CLI.

Este guia pressupõe que você conhece o recurso Extensões do Firebase e como usar essa funcionalidade nos seus apps.

O que posso fazer com o emulador das extensões?

Com o emulador do recurso Extensões, é 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 de faturamento. O emulador executa as funções das extensões localmente, incluindo as acionadas por eventos em segundo plano, usando os emuladores do Cloud Firestore, Realtime Database, Cloud Storage para Firebase, Authentication e Pub/Sub, além das funções acionadas pelo Eventarc implementadas no Cloud Functions v2.

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

Instalar e avaliar uma extensão

É fácil usar o emulador das extensões 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 gatilho vai usar automaticamente os emuladores do Cloud Firestore e do 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 Pacote de emuladores locais normalmente.

    firebase emulators:start

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

Use a IU do Pacote de emuladores para adicionar dados à coleção de documentos de e-mail e configurar outros recursos de back-end, conforme exigido pela extensão do e-mail acionador.

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ê invocaria o Pacote de emuladores locais para executar seu script de teste:

firebase emulators:exec my-test.sh

Qual é a diferença entre a produção e os testes com o emulador do recurso Extensões?

Com o emulador das extensões, é 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

Atualmente, o Pacote de emuladores locais do Firebase tem suporte apenas a funções acionadas por solicitações HTTP, a gatilhos de eventos personalizados do Eventarc para extensões e a funções acionadas por eventos em segundo plano para Cloud Firestore, Realtime Database, Cloud Storage para 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