Ir para o console

Emulador do Firebase Realtime Database

O emulador do Realtime Database foi desenvolvido para facilitar a escrita de testes de unidade que verificam o comportamento das regras de segurança do seu banco de dados.

De maneira geral, é possível executar todo seu aplicativo no emulador local em vez de usar um banco de dados de produção. No entanto, você enfrentará alguns problemas. Mais especificamente, a integração com o Firebase Auth apresenta falhas. Estamos trabalhando para melhorar esse processo mas, por enquanto, recomendamos que você tente escrever alguns testes para garantir que suas regras de segurança funcionem conforme o esperado.

Quando o emulador for iniciado, seu banco de dados será "bloqueado" do ponto de vista da segurança. Tanto ".read" como ".write" serão falsos. Antes da gravação, será preciso definir suas regras de segurança. Você pode fazer isso diretamente de dentro de uma biblioteca de teste de unidade usando o módulo SDK de teste, como descrito abaixo.

Como sempre, ficaremos felizes em receber seu feedback. Envie sua opinião.

Diferenças entre o emulador e a produção

  1. Você não precisa criar uma instância de banco de dados de maneira explícita. O emulador criará automaticamente qualquer instância de banco de dados que for acessada.
  2. Cada novo banco de dados é iniciado com regras fechadas. Dessa forma, usuários que não forem administradores não terão permissão para realizar operações de leitura ou gravação.
  3. Cada banco de dados emulado aplica os limites e as cotas do plano do Spark (principalmente, isso limita cada instância a 100 conexões simultâneas).
  4. Qualquer banco de dados aceitará a string "owner" como um token de autenticação de administrador.
    1. Se você quiser usar a API REST como administrador, inclua o cabeçalho
      Authorization: Bearer owner.
    2. Você pode usar isso para definir regras com curl. Supondo que suas regras estejam em um arquivo database.rules.json, o comando a seguir deve funcionar:
      curl -X PUT -H 'Authorization: Bearer owner' --data @database.rules.json http://localhost:9000/.settings/rules.json?ns=<name>
  5. O emulador de banco de dados não interage ativamente com outros produtos do Firebase. Além disso, é importante ressaltar que o fluxo normal de autenticação do Firebase não funcionará. Em vez disso, fornecemos o método initializeTestApp() no módulo de teste, que recebe um campo auth. O gerenciador do Firebase criado a partir desse método se comportará como se tivesse sido autenticado da mesma forma que qualquer entidade fornecida por você. Caso null seja transmitido, ele se comportará como um usuário não autenticado. Por exemplo, as regras auth != null apresentarão falha.

Instalar o emulador

Para instalar o emulador do Realtime Database, use a Firebase CLI e execute o comando abaixo:

firebase setup:emulators:database

Executar o emulador

Inicie o emulador usando o comando a seguir. O emulador será executado até você encerrar o processo:

firebase emulators:start --only database

O emulador do Realtime Database requer o Java 8 ou superior.

Em muitos casos, você quer iniciar o emulador, executar um conjunto de testes e, em seguida, desligar o emulador após a execução dos testes. É possível fazer isso facilmente usando o comando emulators:exec:

firebase emulators:exec --only database "./my-test-script.sh"

Quando iniciado, o emulador tentará ser executado em uma porta padrão (5003). É possível alterar a porta do emulador modificando a seção "emulators" do arquivo firebase.json:

{
  // ...
  "emulators": {
    "database": {
      "port": "YOUR_PORT"
    }
  }
}

Interagir com o emulador

Uma instância normal do Firebase Realtime Database é acessível em um subdomínio de firebaseio.com. Acesse a API REST usando o seguinte comando:

https://<database_name>.firebaseio.com/path/to/my/data.json

O emulador é executado localmente e está disponível em localhost:9000. Para interagir com uma instância de banco de dados específica, você precisará usar um parâmetro de consulta a fim de especificar o nome desse banco de dados.

http://localhost:9000/path/to/my/data.json?ns=<database_name>

Fornecemos o módulo @firebase/testing para facilitar a interação com o emulador que usa o SDK do Firebase. Com o módulo @firebase/testing, é possível interagir com uma versão executada localmente do emulador do Realtime Database. Se você encontrar erros de tempo limite ou ECONNREFUSED, verifique novamente se o emulador está em execução.

É altamente recomendável o uso de uma versão recente do Node.js para utilizar a notação async/await. Quase todo o comportamento que pode ser testado envolve funções assíncronas, e o módulo de teste é projetado para funcionar com código baseado em promessas.

O módulo expõe os seguintes métodos:

initializeTestApp({ databaseName: , auth: }) => FirebaseApp

Use esse método para criar um aplicativo autenticado como um usuário específico a ser utilizado em testes.

Ele retorna um aplicativo do Firebase inicializado correspondente ao nome do banco de dados e à modificação da variável de autenticação especificada nas opções. Observação: ele NÃO usa o databaseURL, já que não está sendo executado em um servidor remoto.

firebase.initializeTestApp({
  databaseName: "my-database",
  auth: { uid: "alice" }
});

initializeAdminApp({ databaseName: }) => FirebaseApp

Use esse método para criar um aplicativo autenticado como administrador e configurar o estado para testes.

Ele retorna um aplicativo de administrador do Firebase inicializado correspondente ao nome do banco de dados especificado nas opções. Esse app ignora as regras de segurança durante a leitura e a gravação no banco de dados.

firebase.initializeAdminApp({ databaseName: "my-database" });

loadDatabaseRules({ databaseName: , rules: }) => Promise

Use esse método para definir as regras do seu banco de dados.

Ele envia regras para um banco de dados executado localmente. Além disso, usa um objeto de opções que especifica "databaseName" e "rules" como strings.

firebase
      .loadDatabaseRules({
        databaseName: "my-database",
        rules: "{'rules': {'.read': false, '.write': false}}"
      });

apps() => [FirebaseApp]

Esse método retorna todos os aplicativos de teste e de administrador inicializados no momento.

Use-o para limpar aplicativos durante e depois dos testes. Observação: os aplicativos inicializados com listeners ativos impedem o JavaScript de finalizar a execução:

 Promise.all(firebase.apps().map(app => app.delete()))

assertFails(pr: Promise) => Promise

Esse método retorna uma promessa que será recusada se a entrada for concluída e que será concluída se a entrada for recusada.

Ele deve ser usado para informar que ocorreu uma falha na leitura ou na gravação no banco de dados:

firebase.assertFails(app.database().ref("secret").once("value"));

assertSucceeds(pr: Promise) => Promise

Esse método retorna uma promessa que será concluída se a entrada for concluída e será recusada se a entrada for recusada.

Ele deve ser usado para informar que uma leitura ou gravação no banco de dados foi concluída:

firebase.assertSucceeds(app.database().ref("public").once("value"));

Gerar relatórios de teste

Depois de executar um conjunto de testes, é possível acessar relatórios de cobertura de teste que mostram como cada uma das suas regras de segurança foi avaliada. Para acessar os relatórios, consulte um ponto de extremidade exposto no emulador enquanto ele está em execução. Para uma versão otimizada para navegadores, use o seguinte URL:

http://localhost:9000/.inspect/coverage?ns=<database_name>

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

http://localhost:9000/.inspect/coverage.json?ns=<database_name>

Guia de início rápido

Se você quiser apenas ver um exemplo bastante simples, consulte o guia de início rápido do JavaScript (em inglês).