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.
| Typ projektu | Funkcje | Używanie z emulatorami |
|---|---|---|
| Real |
Prawdziwy projekt Firebase to taki, który został utworzony i skonfigurowany (najprawdopodobniej w konsoli Firebase). Prawdziwe projekty mają aktywne zasoby, takie jak instancje bazy danych, kontenery magazynu, funkcje lub inne zasoby skonfigurowane w danym projekcie Firebase. |
Podczas pracy z prawdziwymi projektami Firebase możesz uruchamiać emulatory dla wszystkich lub niektórych obsługiwanych usług. W przypadku usług, których nie emulujesz, Twoje aplikacje i kod będą wchodzić w interakcję z aktywnymi zasobami (instancjami baz danych, zasobnikami, funkcjami itp.). |
| Prezentacja |
Demonstracyjny projekt Firebase nie ma rzeczywistej konfiguracji Firebase i żadnych zasobów w produkcji. Do tych projektów zwykle uzyskuje się dostęp za pomocą ćwiczeń z programowania lub innych samouczków. Identyfikatory projektów demonstracyjnych mają prefiks |
Podczas pracy z demonstracyjnymi projektami Firebase aplikacje i kod będą wchodzić w interakcje z emulatorami tylko. Jeśli aplikacja próbuje wchodzić w interakcję z zasobem, dla którego nie działa emulowany system, kod nie zadziała. |
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 będzie 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 w emulatorze, 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 wersjilocalhost: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ą 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 dotyczącym wielu baz danych.
Kotlin+KTX
// 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
}
Java
// 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);
Swift
let settings = Firestore.firestore().settings settings.host = "127.0.0.1:8080" settings.cacheSettings = MemoryCacheSettings() settings.isSSLEnabled = false Firestore.firestore().settings = settings
Web
import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";
// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);
Web
// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
db.useEmulator("127.0.0.1", 8080);
}
Aby przetestować 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 ustawiono za pomocą wiersza poleceń Firebase.
Identyfikator projektu możesz przekazać do funkcji initializeApp bezpośrednio lub ustawić zmienną środowiskową GCLOUD_PROJECT.
Pakiet Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
Zmienna środowiskowa
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 do tego celu.Można go wywołać z poziomu kroku konfiguracji lub czyszczenia ramki testowej, z poziomu klasy testowej lub z powłoki (np. za pomocą polecenia 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 wywoływać 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 przeprowadzania testów 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ł
Podczas dodawania reguł 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 odsłoniętego punktu końcowego w emulatorze, gdy jest on uruchomiony. Aby wyświetlić 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 emulowanym środowisku Cloud Functions for Firebase znajdziesz w artykule Uruchamianie funkcji lokalnie.