Połącz swoją aplikację z emulatorem Cloud Firestore

Zanim połączysz swoją aplikację z emulatorem Cloud Firestore, upewnij się, że rozumiesz ogólny przepływ pracy w pakiecie Firebase Local Emulator Suite oraz że instalujesz i konfigurujesz Local Emulator Suite oraz przeglądasz jego polecenia CLI .

Wybierz projekt Firebase

Pakiet emulatorów lokalnych Firebase emuluje produkty dla jednego projektu Firebase.

Aby wybrać projekt do użycia, przed uruchomieniem emulatorów, w CLI uruchom firebase use w swoim katalogu roboczym. Lub możesz przekazać flagę --project do każdego polecenia emulatora.

Local Emulator Suite obsługuje emulację rzeczywistych projektów Firebase i projektów demonstracyjnych .

Typ projektu Cechy Używaj z emulatorami
Prawdziwy

Prawdziwy projekt Firebase to taki, który utworzyłeś i skonfigurowałeś (najprawdopodobniej za pomocą konsoli Firebase).

Prawdziwe projekty mają aktywne zasoby, takie jak instancje bazy danych, zasobniki pamięci, funkcje lub inne zasoby skonfigurowane dla tego projektu Firebase.

Pracując z prawdziwymi projektami Firebase, możesz uruchomić emulatory dla dowolnego lub wszystkich obsługiwanych produktów.

W przypadku jakichkolwiek produktów, których nie emulujesz, Twoje aplikacje i kod będą wchodzić w interakcję z aktywnym zasobem (instancją bazy danych, zasobnikiem pamięci, funkcją itp.).

Próbny

Projekt demonstracyjny Firebase nie ma rzeczywistej konfiguracji Firebase ani aktywnych zasobów. Dostęp do tych projektów można zwykle uzyskać za pośrednictwem ćwiczeń z programowania lub innych samouczków.

Identyfikatory projektów dla projektów demonstracyjnych mają demo- demo.

Podczas pracy z projektami demonstracyjnymi Firebase Twoje aplikacje i kod współdziałają tylko z emulatorami . Jeśli aplikacja spróbuje wejść w interakcję z zasobem, dla którego emulator nie jest uruchomiony, ten kod zakończy się niepowodzeniem.

W miarę możliwości zalecamy korzystanie z projektów demonstracyjnych. Korzyści obejmują:

  • Łatwiejsza konfiguracja, ponieważ możesz uruchamiać emulatory bez tworzenia projektu Firebase
  • Większe bezpieczeństwo, ponieważ jeśli Twój kod przypadkowo wywoła nieemulowane (produkcyjne) zasoby, nie ma szans na zmianę danych, wykorzystanie i rozliczenia
  • Lepsza obsługa offline, ponieważ nie ma potrzeby dostępu do Internetu, aby pobrać konfigurację SDK.

Instrumentacja aplikacji, aby rozmawiać z emulatorami

Platformy Android, Apple i internetowe pakiety SDK

Skonfiguruj konfigurację w aplikacji lub klasy testowe do interakcji z Cloud Firestore w następujący sposób.

Android
        // 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);
Szybki
let settings = Firestore.firestore().settings
settings.host = "localhost:8080"
settings.isPersistenceEnabled = false 
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

Web version 9

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

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, 'localhost', 8080);

Web version 8

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

Do testowania funkcji Cloud Functions uruchamianych przez zdarzenia Firestore za pomocą emulatora nie jest wymagana żadna dodatkowa konfiguracja. Gdy uruchomione są emulatory Firestore i Cloud Functions, automatycznie współpracują ze sobą.

Pakiety SDK administratora

Pakiety SDK Firebase Admin automatycznie łączą się z emulatorem Cloud Firestore, gdy ustawiona jest zmienna środowiskowa FIRESTORE_EMULATOR_HOST :

export FIRESTORE_EMULATOR_HOST="localhost:8080"

Jeśli Twój kod działa w emulatorze Cloud Functions, identyfikator projektu i inna konfiguracja zostaną automatycznie ustawione podczas wywoływania initalizeApp .

Jeśli chcesz, aby kod pakietu Admin SDK łączył się z udostępnionym emulatorem działającym w innym środowisku, musisz podać ten sam identyfikator projektu, który został ustawiony za pomocą interfejsu wiersza polecenia Firebase . Możesz przekazać identyfikator projektu, aby bezpośrednio initializeApp lub ustawić zmienną środowiskową GCLOUD_PROJECT .

Pakiet SDK administratora Node.js
admin.initializeApp({ projectId: "your-project-id" });
Zmienna środowiskowa
export GCLOUD_PROJECT="your-project-id"

Wyczyść bazę danych między testami

Production Firestore nie zapewnia metody SDK platformy do opróżniania bazy danych, ale emulator Firestore udostępnia specjalnie do tego celu punkt końcowy REST, który można wywołać z etapu konfiguracji/odrywania platformy testowej, z klasy testowej lub z powłoki (np. , z curl ) przed rozpoczęciem testu. Możesz użyć tego podejścia jako alternatywy dla zwykłego zamknięcia procesu emulatora.

W odpowiedniej metodzie wykonaj operację HTTP DELETE, podając swój identyfikator projektu Firebase, na przykład firestore firestore-emulator-example , do następującego punktu końcowego:

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

Oczywiście twój kod powinien poczekać na potwierdzenie REST, czy opróżnianie zakończyło się lub nie powiodło się.

Możesz wykonać tę operację z powłoki:

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

Po zaimplementowaniu takiego kroku możesz sekwencjonować testy i uruchamiać funkcje, mając pewność, że stare dane zostaną usunięte między uruchomieniami i używasz nowej konfiguracji testu bazowego.

Importuj i eksportuj dane

Emulatory bazy danych i Cloud Storage umożliwiają eksportowanie danych z działającej instancji emulatora. Zdefiniuj podstawowy zestaw danych do użycia w testach jednostkowych lub przepływach pracy ciągłej integracji, a następnie wyeksportuj go, aby udostępnić go zespołowi.

firebase emulators:export ./dir

W testach podczas uruchamiania emulatora zaimportuj dane linii bazowej.

firebase emulators:start --import=./dir

Możesz poinstruować emulator, aby wyeksportował dane po zamknięciu, określając ścieżkę eksportu lub po prostu używając ścieżki przekazanej do flagi --import .

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

Te opcje importu i eksportu danych działają również z poleceniem firebase emulators:exec . Więcej informacji można znaleźć w opisie poleceń emulatora .

Wizualizuj aktywność reguł bezpieczeństwa

Podczas pracy z pętlami prototypowymi i testowymi możesz korzystać z narzędzi wizualizacyjnych i raportów dostarczanych przez Local Emulator Suite.

Użyj monitora żądań

Emulator Cloud Firestore umożliwia wizualizację żądań klientów w interfejsie użytkownika pakietu emulatorów, w tym śledzenie oceny dla reguł zabezpieczeń Firebase.

Otwórz kartę Firestore > Żądania , aby wyświetlić szczegółową sekwencję oceny dla każdego żądania.

Monitor żądań emulatora Firestore pokazujący oceny reguł bezpieczeństwa

Wizualizuj raporty z ocen reguł

Gdy dodasz reguły bezpieczeństwa do swojego prototypu, możesz je debugować za pomocą narzędzi debugowania pakietu Local Emulator Suite.

Po uruchomieniu zestawu testów możesz uzyskać dostęp do raportów dotyczących pokrycia testami, które pokazują, w jaki sposób oceniono każdą z Twoich reguł bezpieczeństwa.

Aby uzyskać raporty, wykonaj zapytanie do odsłoniętego punktu końcowego w emulatorze, gdy jest on uruchomiony. Aby uzyskać wersję przyjazną dla przeglądarki, użyj następującego adresu URL:

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

Spowoduje to rozbicie reguł na wyrażenia i podwyrażenia, na które można najechać kursorem myszy, aby uzyskać więcej informacji, w tym liczbę zwróconych ocen i wartości. W przypadku nieprzetworzonej wersji tych danych w formacie JSON w zapytaniu uwzględnij następujący adres URL:

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

Tutaj wersja HTML raportu wyróżnia oceny, które generują błędy niezdefiniowane i o wartości null:

Czym emulator Cloud Firestore różni się od wersji produkcyjnej

Emulator Cloud Firestore stara się wiernie odtworzyć zachowanie usługi produkcyjnej z pewnymi istotnymi ograniczeniami.

Transakcje

Emulator nie implementuje obecnie wszystkich zachowań transakcji widocznych w środowisku produkcyjnym. Podczas testowania funkcji, które obejmują wiele równoczesnych zapisów w jednym dokumencie, emulator może powoli realizować żądania zapisu. W niektórych przypadkach zwolnienie blokady może zająć do 30 sekund. W razie potrzeby rozważ odpowiednie dostosowanie limitów czasu testu.

Indeksy

Emulator nie śledzi indeksów złożonych i zamiast tego wykona każde prawidłowe zapytanie. Przetestuj swoją aplikację na prawdziwej instancji Cloud Firestore, aby określić, jakich indeksów będziesz potrzebować.

Limity

Emulator nie wymusza wszystkich limitów narzuconych w środowisku produkcyjnym. Na przykład emulator może zezwalać na transakcje, które zostałyby odrzucone jako zbyt duże przez usługę produkcyjną. Upewnij się, że znasz udokumentowane ograniczenia i że projektujesz swoją aplikację tak, aby aktywnie ich unikać.

Co następne?

  • Aby zapoznać się z wyselekcjonowanym zestawem filmów i szczegółowymi przykładami instrukcji, skorzystaj z playlisty szkoleniowej na temat emulatorów Firebase .
  • Zbadaj zaawansowane przypadki użycia obejmujące testowanie reguł bezpieczeństwa i pakiet Firebase Test SDK: Testuj reguły bezpieczeństwa (Firestore) .
  • Wyzwalane funkcje to typowa integracja z Cloud Firestore, więc dowiedz się więcej o emulatorze Cloud Functions for Firebase w sekcji Uruchom funkcje lokalnie .