Conecte seu aplicativo ao emulador do Cloud Firestore

Antes de conectar seu aplicativo ao emulador do Cloud Firestore, certifique-se de entender o fluxo de trabalho geral do Firebase Local Emulator Suite e de instalar e configurar o Local Emulator Suite e revisar seus comandos CLI .

Escolha um projeto do Firebase

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

Para selecionar o projeto a ser usado, antes de iniciar os emuladores, na CLI, execute firebase use em seu diretório de trabalho. Ou você pode passar o sinalizador --project para cada comando do emulador.

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

Recomendamos que você use projetos de demonstração sempre que possível. Os benefícios incluem:

• Configuração mais fácil, pois você pode executar os emuladores sem nunca criar um projeto Firebase
• Maior segurança, pois se o seu código invocar acidentalmente recursos não emulados (de produção), não há chance de alteração de dados, utilização e cobrança
• Melhor suporte offline, já que não há necessidade de acesso à internet para baixar a configuração do seu SDK.

Instrumente seu aplicativo para conversar com os emuladores

Na inicialização, o emulador do Cloud Firestore cria um banco de dados padrão e um banco de dados nomeado para cada configuração firestore no arquivo firebase.json . Use seu arquivo firebase.json para atribuir explicitamente regras de segurança do Cloud Firestore a um banco de dados nomeado.

Os bancos de dados nomeados também são criados implicitamente em resposta a quaisquer chamadas de SDK ou API REST para o emulador que fazem referência a um banco de dados específico. Esses bancos de dados criados implicitamente operam com regras abertas .

Atualmente, a UI do Emulator Suite oferece suporte ao trabalho interativo com o banco de dados padrão .

Android, plataformas Apple e SDKs da Web

Defina sua configuração no aplicativo ou classes de teste para interagir com o Cloud Firestore da seguinte maneira. Observe que nos exemplos a seguir, o código do aplicativo está se conectando ao banco de dados do projeto padrão. Para exemplos envolvendo bancos de dados adicionais do Cloud Firestore além do banco de dados padrão, consulte o guia para vários bancos de dados .

// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}
EmulatorSuite.kt

// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
EmulatorSuite.java

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);
fs_emulator_connect.js

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}
emulator-suite.js

Nenhuma configuração adicional é necessária para testar o Cloud Functions acionado por eventos do Firestore usando o emulador. Quando os emuladores do Firestore e do Cloud Functions estão em execução, eles funcionam juntos automaticamente.

SDKs de administração

Os SDKs Admin do Firebase se conectam automaticamente ao emulador do Cloud Firestore quando a variável de ambiente FIRESTORE_EMULATOR_HOST é definida:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Se o código estiver em execução dentro do emulador do Cloud Functions, o ID do projeto e outras configurações serão definidos automaticamente ao chamar initializeApp .

Se quiser que o código do SDK Admin se conecte a um emulador compartilhado em execução em outro ambiente, você precisará especificar o mesmo ID do projeto definido usando a CLI do Firebase . Você pode passar um ID de projeto diretamente para initializeApp ou definir a variável de ambiente GCLOUD_PROJECT .

admin.initializeApp({ projectId: "your-project-id" });

export GCLOUD_PROJECT="your-project-id"

Limpe seu banco de dados entre testes

O Production Firestore não fornece nenhum método SDK de plataforma para liberar o banco de dados, mas o emulador do Firestore fornece um endpoint REST especificamente para essa finalidade, que pode ser chamado a partir de uma etapa de configuração/desmontagem da estrutura de teste, de uma classe de teste ou do shell (por exemplo, , com curl ) antes de um teste ser iniciado. Você pode usar essa abordagem como uma alternativa a simplesmente encerrar o processo do emulador.

Em um método apropriado, execute uma operação HTTP DELETE, fornecendo seu projectID do Firebase, por exemplo firestore-emulator-example , para o seguinte endpoint:

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Naturalmente, seu código deve aguardar a confirmação REST de que a liberação foi concluída ou falhou.

Você pode realizar esta operação no shell:

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Tendo implementado uma etapa como esta, você pode sequenciar seus testes e acionar suas funções com a confiança de que os dados antigos serão eliminados entre as execuções e você estará usando uma nova configuração de teste de linha de base.

Importar e exportar dados

O banco de dados e os emuladores do Cloud Storage para Firebase permitem exportar dados de uma instância do emulador em execução. Defina um conjunto básico de dados para usar em seus testes de unidade ou fluxos de trabalho de integração contínua e, em seguida, exporte-os para serem compartilhados entre a equipe.

firebase emulators:export ./dir

Nos testes, na inicialização do emulador, importe os dados da linha de base.

firebase emulators:start --import=./dir

Você pode instruir o emulador a exportar dados no desligamento, especificando um caminho de exportação ou simplesmente usando o caminho passado para o sinalizador --import .

firebase emulators:start --import=./dir --export-on-exit

Essas opções de importação e exportação de dados também funcionam com o comando firebase emulators:exec . Para obter mais informações, consulte a referência do comando do emulador .

Visualize a atividade das regras de segurança

À medida que você trabalha nos protótipos e nos loops de teste, você pode usar ferramentas de visualização e relatórios fornecidos pelo Local Emulator Suite.

Use o Monitor de Solicitações

O emulador do Cloud Firestore permite visualizar solicitações de clientes na IU do Emulator Suite, incluindo rastreamento de avaliação para regras de segurança do Firebase.

Abra a guia Firestore > Solicitações para visualizar a sequência de avaliação detalhada de cada solicitação.

Visualize relatórios de avaliações de regras

Ao adicionar regras de segurança ao seu protótipo, você pode depurá-las com as ferramentas de depuração do Local Emulator Suite.

Depois de executar um conjunto de testes, você poderá acessar relatórios de cobertura de testes que mostram como cada uma de suas regras de segurança foi avaliada.

Para obter os relatórios, consulte um ponto de extremidade exposto no emulador enquanto ele estiver em execução. Para uma versão amigável ao navegador, use o seguinte URL:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

Isso divide suas regras em expressões e subexpressões que você pode passar o mouse para obter mais informações, incluindo o número de avaliações e valores retornados. Para a versão JSON bruta desses dados, inclua o seguinte URL na sua consulta:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

Aqui, a versão HTML do relatório destaca avaliações que geram erros indefinidos e de valor nulo:

Como o emulador do Cloud Firestore difere da produção

O Cloud Firestore Emulator tenta replicar fielmente o comportamento do serviço de produção com algumas limitações notáveis.

Suporte a vários bancos de dados para Cloud Firestore

Atualmente, a interface do usuário do Emulator Suite dá suporte à criação, edição, exclusão, monitoramento de solicitação e visualização de segurança interativas para um banco de dados padrão, mas não para bancos de dados nomeados adicionais.

No entanto, o próprio emulador cria um banco de dados nomeado com base na configuração do arquivo firebase.json e implicitamente em resposta a chamadas de SDK ou API REST.

Transações

Atualmente, o emulador não implementa todos os comportamentos de transação vistos na produção. Ao testar recursos que envolvem várias gravações simultâneas em um documento, o emulador pode demorar para concluir as solicitações de gravação. Em alguns casos, os bloqueios podem levar até 30 segundos para serem liberados. Considere ajustar os tempos limite dos testes adequadamente, se necessário.

Índices

O emulador não rastreia índices compostos e, em vez disso, executará qualquer consulta válida. Certifique-se de testar seu aplicativo em uma instância real do Cloud Firestore para determinar quais índices você precisará.

Limites

O emulador não impõe todos os limites impostos na produção. Por exemplo, o emulador pode permitir transações que seriam rejeitadas como muito grandes pelo serviço de produção. Certifique-se de estar familiarizado com os limites documentados e de projetar seu aplicativo para evitá-los proativamente.

Qual o proximo?

• Para ver um conjunto selecionado de vídeos e exemplos detalhados de instruções, siga a lista de reprodução de treinamento do Firebase Emulators .
• Investigue casos de uso avançados envolvendo testes de regras de segurança e o Firebase Test SDK: Test Security Rules (Firestore) .
• Como as funções acionadas são uma integração típica com o Cloud Firestore, saiba mais sobre o emulador do Cloud Functions para Firebase em Executar funções localmente .