Łączenie aplikacji z emulatorem Cloud Firestore

Zanim połączysz aplikację z emulatorem Cloud Firestore, zapoznaj się z całym procesem Firebase Local Emulator Suite oraz zainstaluj i skonfiguruj Local Emulator Suite i sprawdź jego polecenia CLI.

Wybieranie projektu Firebase

Firebase Local Emulator Suite emuluje usługi w pojedynczym projekcie Firebase.

Aby wybrać projekt, który ma być używany, przed uruchomieniem emulatorów uruchom w CLI polecenie firebase use w katalogu roboczym. Możesz też przekazać parametr --project do każdego polecenia emulatora.

Local Emulator Suite obsługuje emulację prawdziwych projektów Firebase oraz projektów demonstracyjnych.

W miarę możliwości zalecamy korzystanie z projektów demonstracyjnych. W ten sposób możesz zapewnić im dostęp do tych korzyści:

• Ł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 możliwości zmiany danych, ich użycia ani rozliczenia.
• lepsza obsługa trybu offline, ponieważ do pobrania konfiguracji pakietu SDK nie jest potrzebne połączenie z internetem;

Przeprowadź testy aplikacji z użyciem emulatorów

Po uruchomieniu emulator Cloud Firestore tworzy domyślną bazę danych i nazwę bazy danych dla każdej konfiguracji firestore w pliku firebase.json.

Nazwane bazy danych są też tworzone pośrednio w odpowiedzi na wywołania interfejsu API pakietu SDK lub interfejsu REST do emulatora, które odwołują się do konkretnej bazy danych. Takie bazy danych tworzone w sposób domyślny działają zgodnie z regułami otwartymi.

Aby w interaktywny sposób pracować z bazami danych domyślnymi i nazwistymi w programie Emulator Suite UI, na pasku adresu przeglądarki zaktualizuj adres URL, aby wybrać bazę domyślną lub nazwaną.

• Aby na przykład przeglądać dane w domyślnej instancji, zaktualizuj adres URL do:localhost:4000/firestore/default/data
• Aby przeglądać instancję o nazwie ecommerce, zaktualizuj ją do wersji localhost:4000/firestore/ecommerce/data.

Pakiety SDK na Androida i platformy Apple oraz pakiety SDK internetowe

Skonfiguruj konfigurację w aplikacji lub przetestuj klasy, aby sprawdzić, czy działają one prawidłowo z usługą Cloud Firestore: Pamiętaj, że w tych przykładach kod aplikacji łączy się z domyślną bazą danych projektu. Przykłady dotyczące dodatkowych baz danych Cloud Firestore oprócz domyślnej znajdziesz w przewodniku po wielu bazach danych.

// 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

Aby przetestować funkcje Cloud Functions uruchamiane przez zdarzenia Firestore za pomocą emulatora, nie musisz nic konfigurować. Gdy emulatory Firestore i Cloud Functions są uruchomione, automatycznie współpracują ze sobą.

Admin SDK s

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Jeśli Twój kod jest uruchamiany w emulatorze Cloud Functions, identyfikator projektu i inne ustawienia konfiguracji są automatycznie ustawiane podczas wywoływania funkcji initializeApp.

Jeśli chcesz, aby kod Admin SDK łączył się z wspólnym emulatorem działającym w innym środowisku, musisz podać ten sam identyfikator projektu, który został ustawiony za pomocą wiersza poleceń Firebase. Identyfikator projektu możesz przekazać do funkcji initializeApp bezpośrednio lub ustawić zmienną środowiskową GCLOUD_PROJECT.

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

export GCLOUD_PROJECT="your-project-id"

Czyszczenie bazy danych między testami

Produkcyjna wersja Firestore nie udostępnia żadnej metody pakietu SDK platformy do czyszczenia bazy danych, ale emulator Firestore udostępnia punkt końcowy REST przeznaczony właśnie do tego celu.Można go wywołać na etapie konfiguracji lub czyszczenia ram testowych, z klasy testowej lub z powłoki (np. za pomocą curl) przed rozpoczęciem testu. Możesz użyć tego podejścia zamiast po prostu zamykania procesu emulatora.

W odpowiedniej metodzie wykonaj operację HTTP DELETE, podając identyfikator projektu Firebase, np. firestore-emulator-example, do tego punktu końcowego:

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

Twój kod powinien oczekiwać na potwierdzenie REST, że czyszczenie się zakończyło lub nie powiodło się.

Możesz wykonać tę operację w powłoce:

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

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

Importowanie i eksportowanie danych

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

firebase emulators:export ./dir

Podczas testów, po uruchomieniu emulatora, zaimportuj dane bazowe.

firebase emulators:start --import=./dir

Możesz zlecić emulatorowi eksportowanie danych po wyłączeniu, 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 importowania i eksportowania danych działają też z poleceniem firebase emulators:exec. Więcej informacji znajdziesz w przewodniku po poleceniach emulatora.

Wizualizacja aktywności reguł zabezpieczeń

Podczas tworzenia prototypów i testowania możesz korzystać z wizualizacji i raportów udostępnianych przez Local Emulator Suite.

Korzystanie z monitora żądań

Emulator Cloud Firestore umożliwia wizualizację żądań klienta w Emulator Suite UI, w tym śledzenie oceny dla Firebase Security Rules.

Aby wyświetlić szczegółową sekwencję oceny dla każdej prośby, otwórz kartę Firestore > Prośby.

Wizualizacja raportów oceny reguł

Gdy dodajesz reguły zabezpieczeń do prototypu, możesz je debugować za pomocą narzędzi do debugowaniaLocal Emulator Suite.

Po uruchomieniu zestawu testów możesz uzyskać dostęp do raportów o zakresie testów, które pokazują, jak oceniono każdą z reguł bezpieczeństwa.

Aby uzyskać raporty, prześlij zapytanie do punktu końcowego w emulatorze, gdy jest on uruchomiony. Aby uzyskać wersję przyjazną przeglądarce, użyj tego adresu URL:

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

Dzięki temu reguły są dzielone na wyrażenia i podwyrażenia, nad którymi możesz najechać kursorem, aby uzyskać więcej informacji, w tym liczbę zwracanych ocen i wartości. Aby uzyskać wersję tych danych w postaci surowego pliku JSON, dodaj do zapytania ten adres URL:

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

W wersji HTML raportu wyróżniono tu oceny, które zwracają błędy związane z niezdefiniowanymi wartościami i wartościami null:

Różnice między emulatorem Cloud Firestore a wersją produkcyjną

Emulator Cloud Firestore stara się wiernie odwzorowywać działanie usługi produkcyjnej, ale ma pewne istotne ograniczenia.

Obsługa wielu baz danych w Cloud Firestore

Obecnie usługa Emulator Suite UI obsługuje interaktywne tworzenie, edytowanie, usuwanie, monitorowanie żądań i wizualizację zabezpieczeń w przypadku domyślnej bazy danych, ale nie dodatkowych nazwanych baz danych.

Jednak sam emulator tworzy nazwaną bazę danych na podstawie konfiguracji w pliku firebase.json i domyślnie w odpowiedzi na wywołania pakietu SDK lub interfejsu REST API.

Transakcje

Emulator nie implementuje obecnie wszystkich zachowań transakcji występujących w środowisku produkcyjnym. Podczas testowania funkcji, które obejmują wiele jednoczesnych zapisów w jednym dokumencie, emulacja może być powolna w wypełnianiu żądań zapisu. W niektórych przypadkach odblokowanie może potrwać do 30 sekund. W razie potrzeby dostosuj czasy oczekiwania na wyniki testów.

Indeksy

Emulator nie śledzi indeksów złożonych, tylko wykonuje dowolne prawidłowe zapytanie. Aby określić, których indeksów potrzebujesz, przetestuj aplikację na prawdziwej instancji Cloud Firestore.

Limity

Emulator nie egzekwuje wszystkich limitów stosowanych w produkcji. Na przykład emulowany system może zezwalać na transakcje, które zostałyby odrzucone przez produkcyjną usługę jako zbyt duże. Zapoznaj się z ograniczeniami i zaprojektuj aplikację tak, aby ich uniknąć.

Co dalej?

• Aby uzyskać dostęp do wyselekcjonowanych filmów i szczegółowych przykładów, skorzystaj z playlisty szkoleń na temat emulatorów Firebase.
• Zapoznaj się z zaawansowanymi przypadkami użycia dotyczącymi testowania reguł zabezpieczeń i pakietu Firebase Test SDK: Testowanie reguł zabezpieczeń (Firestore).
• Funkcja wywoływana jest typową integracją z Cloud Firestore. Więcej informacji o emulatorze Cloud Functions for Firebase znajdziesz w artykule Uruchamianie funkcji lokalnie.