Przed połączeniem aplikacji z emulatorem Cloud Firestore upewnij się, że rozumiesz ogólny przepływ pracy w pakiecie Firebase Local Emulator Suite , instalujesz i konfigurujesz pakiet Local Emulator Suite oraz przeglądasz jego polecenia CLI .
Wybierz projekt Firebase
Firebase Local Emulator Suite emuluje produkty dla pojedynczego 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ę prawdziwych 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 baz danych, zasobniki pamięci, funkcje lub wszelkie inne zasoby skonfigurowane dla tego projektu Firebase. | Pracując z prawdziwymi projektami Firebase, możesz uruchamiać emulatory dla dowolnego lub wszystkich obsługiwanych produktów. W przypadku produktów, których nie emulujesz, Twoje aplikacje i kod będą wchodzić w interakcje z aktywnym zasobem (instancja bazy danych, zasobnik pamięci, funkcja itp.). |
| Próbny | Demonstracyjny projekt Firebase nie ma rzeczywistej konfiguracji Firebase ani aktywnych zasobów. Projekty te są zwykle dostępne za pośrednictwem laboratoriów kodów lub innych samouczków. Identyfikatory projektów dla projektów demonstracyjnych mają przedrostek | Podczas pracy z demonstracyjnymi projektami Firebase Twoje aplikacje i kod współdziałają tylko z emulatorami . Jeśli Twoja aplikacja spróbuje wejść w interakcję z zasobem, dla którego nie działa emulator, 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 rozliczenie
- Lepsze wsparcie offline, ponieważ nie ma potrzeby dostępu do Internetu, aby pobrać konfigurację SDK.
Przygotuj swoją aplikację do komunikowania się z emulatorami
Podczas uruchamiania emulator Cloud Firestore tworzy domyślną bazę danych i nazwaną bazę danych dla każdej konfiguracji firestore w pliku firebase.json . Użyj pliku firebase.json , aby jawnie przypisać reguły bezpieczeństwa Cloud Firestore do nazwanej bazy danych.
Nazwane bazy danych są również tworzone niejawnie w odpowiedzi na wywołania dowolnego zestawu SDK lub interfejsu API REST do emulatora, które odwołują się do określonej bazy danych. Takie niejawnie tworzone bazy danych działają według otwartych reguł .
Obecnie interfejs Emulator Suite obsługuje interaktywną pracę z domyślną bazą danych .
Platformy Android, Apple i Web SDK
Skonfiguruj konfigurację w aplikacji lub klasy testowe do interakcji z Cloud Firestore w następujący sposób. Należy zauważyć, że w poniższych przykładach kod aplikacji łączy się z domyślną bazą danych projektu. Aby zapoznać się z przykładami dotyczącymi dodatkowych baz danych Cloud Firestore poza domyślną bazą danych, zapoznaj się z przewodnikiem 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);
Szybki
let settings = Firestore.firestore().settings settings.host = "127.0.0.1:8080" settings.isPersistenceEnabled = false settings.isSSLEnabled = false Firestore.firestore().settings = settings
Web modular API
import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";
// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);Web namespaced API
// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
db.useEmulator("127.0.0.1", 8080);
}Do testowania funkcji Cloud Functions wyzwalanych przez zdarzenia Firestore za pomocą emulatora nie jest wymagana żadna dodatkowa konfiguracja. Kiedy oba emulatory Firestore i Cloud Functions są uruchomione, 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="127.0.0.1:8080"
Jeśli Twój kod działa w emulatorze Cloud Functions, Twój identyfikator projektu i inna konfiguracja są ustawiane automatycznie podczas wywoływania initializeApp .
Jeśli chcesz, aby Twój kod Admin SDK łączył się z udostępnionym emulatorem działającym w innym środowisku, musisz podać ten sam identyfikator projektu, który ustawiłeś za pomocą Firebase CLI . Możesz przekazać identyfikator projektu bezpośrednio do 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 udostępnia żadnej metody platformy SDK do opróżniania bazy danych, ale emulator Firestore zapewnia punkt końcowy REST specjalnie do tego celu, który można wywołać z kroku konfiguracji/tearDown platformy testowej, z klasy testowej lub z powłoki (np. za pomocą curl ) przed rozpoczęciem testu. Możesz użyć tego podejścia jako alternatywy dla zwykłego zamykania procesu emulatora.
W odpowiedniej metodzie wykonaj operację HTTP DELETE, podając identyfikator projektu Firebase, na przykład 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 czekać na potwierdzenie REST, że opróżnianie zakończyło się lub nie powiodło.
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ć swoje funkcje, mając pewność, że stare dane zostaną wyczyszczone między uruchomieniami i używasz nowej konfiguracji testu linii bazowej.
Importuj i eksportuj dane
Baza danych i emulatory Cloud Storage for Firebase umożliwiają eksportowanie danych z działającej instancji emulatora. Zdefiniuj podstawowy zestaw danych do wykorzystania 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 podczas zamykania, 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 . Aby uzyskać więcej informacji, zapoznaj się z dokumentacją poleceń emulatora .
Wizualizuj działanie zasad bezpieczeństwa
Pracując nad pętlami prototypowymi i testowymi, możesz korzystać z narzędzi do wizualizacji i raportów dostarczanych przez pakiet Local Emulator Suite.
Skorzystaj z Monitora żądań
Emulator Cloud Firestore umożliwia wizualizację żądań klientów w interfejsie Emulator Suite, w tym śledzenie oceny reguł bezpieczeństwa Firebase.
Otwórz kartę Firestore > Żądania , aby wyświetlić szczegółową sekwencję oceny dla każdego żądania.
Wizualizuj raporty oceny reguł
Dodając reguły bezpieczeństwa do swojego prototypu, możesz je debugować za pomocą narzędzi do debugowania pakietu Local Emulator Suite.
Po przeprowadzeniu zestawu testów możesz uzyskać dostęp do raportów pokrycia testów, które pokazują, jak oceniono każdą z reguł bezpieczeństwa.
Aby uzyskać raporty, wyślij zapytanie do uwidocznionego 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 wyrażenia podrzędne, na które można najechać kursorem myszy, aby uzyskać więcej informacji, w tym liczbę ocen i zwróconych wartości. Aby uzyskać nieprzetworzoną wersję 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 zgłaszają niezdefiniowane błędy i błędy o wartości pustej:
Czym emulator Cloud Firestore różni się od produkcyjnego
Emulator Cloud Firestore próbuje wiernie odtworzyć zachowanie usługi produkcyjnej z pewnymi znaczącymi ograniczeniami.
Obsługa wielu baz danych dla Cloud Firestore
Obecnie interfejs użytkownika Emulator Suite obsługuje interaktywne tworzenie, edytowanie, usuwanie, monitorowanie żądań i wizualizację zabezpieczeń dla domyślnej bazy danych, ale nie obsługuje dodatkowych nazwanych baz danych.
Jednak sam emulator tworzy nazwaną bazę danych na podstawie konfiguracji w pliku firebase.json i niejawnie w odpowiedzi na wywołania SDK lub API REST.
Transakcje
Emulator obecnie nie implementuje wszystkich zachowań transakcji obserwowanych w środowisku produkcyjnym. Podczas testowania funkcji obejmujących wiele jednoczesnych zapisów w jednym dokumencie emulator może wolno wykonywać żądania zapisu. W niektórych przypadkach zwolnienie blokady może potrwać do 30 sekund. W razie potrzeby rozważ odpowiednie dostosowanie limitów czasu testów.
Indeksy
Emulator nie śledzi indeksów złożonych i zamiast tego wykona dowolne prawidłowe zapytanie. Pamiętaj, aby przetestować swoją aplikację na rzeczywistej instancji Cloud Firestore, aby określić, które indeksy będą potrzebne.
Granice
Emulator nie wymusza wszystkich ograniczeń narzuconych w środowisku produkcyjnym. Na przykład emulator może zezwolić na transakcje, które zostałyby odrzucone jako zbyt duże przez usługę produkcyjną. Upewnij się, że znasz udokumentowane ograniczenia i że projektujesz aplikację tak, aby proaktywnie ich unikać.
Co następne?
- Aby zapoznać się z wyselekcjonowanym zestawem filmów i szczegółowymi przykładami, postępuj zgodnie z listą odtwarzania szkoleniowych emulatorów Firebase .
- Zbadaj zaawansowane przypadki użycia obejmujące testowanie reguł bezpieczeństwa i pakiet SDK testowy Firebase: Testuj reguły bezpieczeństwa (Firestore) .
- Ponieważ wyzwalane funkcje są typową integracją z Cloud Firestore, dowiedz się więcej o emulatorze Cloud Functions for Firebase na stronie Uruchom funkcje lokalnie .