Testar o modo Datastore usando o emulador do Firestore

A Google Cloud CLI fornece um emulador local na memória para o Firestore que pode ser usado para testar o Firestore no aplicativo no modo Datastore. Você pode usar o emulador com todas as bibliotecas de cliente do modo Datastore. Use o emulador apenas para testes locais.

Use gcloud emulators firestore com --database-mode=datastore-mode para testar o comportamento do Firestore no modo Datastore.

Não use o emulador para implantações de produção. Como o emulador armazena dados apenas na memória, ele não mantém dados entre execuções.

Instalar o emulador

Para instalar o emulador do Firestore, instale e atualize a CLI gcloud:

  1. Instale a CLI da gcloud.

  2. Atualize a instalação da CLI da gcloud para receber os recursos mais recentes:

    gcloud components update

Executar o emulador

  1. Execute o seguinte comando para iniciar o emulador:

    gcloud emulators firestore start --database-mode=datastore-mode

    O emulador imprime o host e o número da porta em que está sendo executado.

    Por padrão, o emulador tenta usar 127.0.0.1:8080. Para vincular o emulador a um host e uma porta específicos, use a sinalização --host-port opcional, substituindo HOST e PORT:

    gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORT

  2. Use o atalho de teclado Control + C para interromper o emulador.

Conectar ao emulador

Para conectar uma biblioteca de cliente e um app ao emulador, defina a variável de ambiente DATASTORE_EMULATOR_HOST. Quando essa variável de ambiente é definida, as bibliotecas de cliente se conectam automaticamente ao emulador.

export DATASTORE_EMULATOR_HOST="HOST:PORT"

Importar entidades para o emulador

O recurso de importação do emulador permite carregar entidades de um conjunto de arquivos de exportação da entidade no emulador. Os arquivos de exportação da entidade podem vir de uma exportação do banco de dados do modo Datastore ou de uma instância do emulador.

Para importar entidades para o emulador, envie uma solicitação de importação POST ao emulador. Use o curl ou uma ferramenta semelhante. Por exemplo, esta solicitação importará todas as entidades de um conjunto de arquivos de exportação da entidade para o emulador:

Protocolo

curl -X POST http://localhost:8080/emulator/v1/projects/[PROJECT_ID]:import \
-H 'Content-Type: application/json' \
-d '{"database":"[DATABASE]", "export_directory":"[EXPORT_DIRECTORY]"}'
Modifique localhost:8080 se o emulador usar uma porta diferente.

onde:

  • [PROJECT_ID] é o ID do projeto;

  • [DATABASE] é o caminho do banco de dados. Por exemplo, um projeto com um banco de dados padrão ficaria assim:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] é o caminho para o arquivo overall_export_metadata dos seus arquivos de exportação de entidade. Exemplo:

    {"export_directory":"/home/user/myexports/2024-03-26T19:39:33_443/2024-03-26T19:39:33_443.overall_export_metadata"}

Exportar entidades no emulador

O recurso de exportação do emulador permite salvar entidades no emulador em um conjunto de arquivos de exportação da entidade. Em seguida, use uma operação de importação para carregar as entidades nos arquivos de exportação da entidade no banco de dados do modo Datastore ou em uma instância do emulador.

Para exportar entidades em uma instância de emulador, envie uma solicitação de exportação POST ao emulador. Use curl ou uma ferramenta semelhante. Por exemplo, esta solicitação exportará todas as entidades no emulador:

Protocolo

curl -X POST http://localhost:8080/emulator/v1/projects/[PROJECT_ID]:export \
-H 'Content-Type: application/json' \
-d '{"database":"[DATABASE_PATH]", "export_directory":"EXPORT_DIRECTORY"}'
Modifique localhost:8080 se o emulador usar uma porta diferente.

onde:

  • [PROJECT_ID] é o ID do projeto;

  • [DATABASE_PATH] é o caminho do banco de dados. Por exemplo, um projeto com um banco de dados padrão ficaria assim:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] especifica o diretório em que o emulador salvará os arquivos de exportação da entidade. Esse diretório não pode conter um conjunto de arquivos de exportação da entidade. Exemplo:

    {"export_directory":"/home/user/myexports/2024-03-26/"}

Redefinir dados do emulador

O emulador do Firestore inclui um endpoint REST para redefinir todos os dados no emulador. Você pode usar esse endpoint para limpar dados entre testes sem encerrar o emulador.

Para redefinir todos os dados no emulador, execute uma operação HTTP POST no endpoint a seguir, substituindo HOST e PORT pelo host e pela porta selecionados e substituindo PROJECT_ID pelo ID do seu projeto:

http://HOST:PORT/reset

Ajuste o host e a porta se o emulador não usar 127.0.0.1:8080. Seu código deve aguardar a confirmação REST de que a redefinição foi concluída ou falhou.

É possível executar essa operação no shell usando curl:

$ curl -X POST "http://HOST:PORT/reset"

Qual é a diferença entre o emulador e a produção

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

Simultaneidade e consistência

O emulador é compatível apenas com simultaneidade pessimista e consistência forte. O emulador não oferece suporte a configurações de simultaneidade otimista e consistência posterior.

Transações

O emulador não implementa todo o comportamento de transação encontrado na produção. Quando você está testando recursos que envolvem várias gravações simultâneas em um documento, o emulador pode demorar para concluir solicitações de gravação. Em alguns casos, os bloqueios podem levar até 30 segundos para serem liberados. Considere ajustar os tempos limites do teste de acordo, se necessário.

Índices

O emulador não rastreia índices compostos e, em vez disso, executa qualquer consulta válida. Teste seu aplicativo em uma instância real do modo Datastore para determinar quais índices são necessários.

Limites

O emulador não impõe todos os limites aplicados na produção. Por exemplo, o emulador pode permitir transações que são rejeitadas por serem muito grandes pelo serviço de produção. Conheça os limites documentados e projete seu app para evitá-los proativamente.

A seguir