Prima di connettere la tua app all'emulatore Cloud Firestore, assicurati di comprendere il flusso di lavoro generale di Firebase Local Emulator Suite e di installare e configurare Local Emulator Suite ed esaminare i relativi comandi CLI .
Scegli un progetto Firebase
La Firebase Local Emulator Suite emula i prodotti per un singolo progetto Firebase.
Per selezionare il progetto da utilizzare, prima di avviare gli emulatori, nella CLI eseguire firebase use nella directory di lavoro. In alternativa, puoi passare il flag --project a ciascun comando dell'emulatore.
Local Emulator Suite supporta l'emulazione di progetti Firebase reali e progetti demo .
| Tipo di progetto | Caratteristiche | Utilizzare con emulatori |
|---|---|---|
| Vero | Un vero progetto Firebase è quello che hai creato e configurato (molto probabilmente tramite la console Firebase). I progetti reali hanno risorse attive, come istanze di database, bucket di archiviazione, funzioni o qualsiasi altra risorsa configurata per quel progetto Firebase. | Quando lavori con progetti Firebase reali, puoi eseguire emulatori per uno o tutti i prodotti supportati. Per tutti i prodotti che non stai emulando, le tue app e il tuo codice interagiranno con la risorsa live (istanza del database, bucket di archiviazione, funzione e così via). |
| Dimostrazione | Un progetto Firebase demo non ha una configurazione Firebase reale né risorse live. Di solito si accede a questi progetti tramite codelab o altri tutorial. Gli ID progetto per i progetti demo hanno il prefisso | Quando lavori con progetti Firebase demo, le tue app e il tuo codice interagiscono solo con gli emulatori. Se la tua app tenta di interagire con una risorsa per la quale non è in esecuzione un emulatore, il codice avrà esito negativo. |
Ti consigliamo di utilizzare progetti demo ove possibile. I vantaggi includono:
- Configurazione più semplice, poiché puoi eseguire gli emulatori senza mai creare un progetto Firebase
- Maggiore sicurezza, poiché se il codice richiama accidentalmente risorse (di produzione) non emulate, non vi è alcuna possibilità di modifica, utilizzo e fatturazione dei dati
- Migliore supporto offline, poiché non è necessario accedere a Internet per scaricare la configurazione dell'SDK.
Strumenti la tua app per comunicare con gli emulatori
All'avvio, l'emulatore Cloud Firestore crea un database predefinito e un database denominato per ogni configurazione firestore nel file firebase.json . Utilizza il file firebase.json per assegnare in modo esplicito le regole di sicurezza di Cloud Firestore a un database denominato.
I database denominati vengono inoltre creati implicitamente in risposta a qualsiasi chiamata SDK o API REST all'emulatore che fa riferimento a un database specifico. Tali database creati implicitamente operano con regole aperte .
Attualmente, l'interfaccia utente di Emulator Suite supporta il lavoro interattivo con il database predefinito .
Piattaforme Android, Apple e SDK Web
Imposta la configurazione in-app o le lezioni di prova per interagire con Cloud Firestore come segue. Tieni presente che negli esempi seguenti il codice dell'app si connette al database del progetto predefinito. Per esempi che coinvolgono database Cloud Firestore aggiuntivi oltre al database predefinito, fai riferimento alla guida per più database .
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);
Veloce
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);
}Non è necessaria alcuna configurazione aggiuntiva per testare le funzioni Cloud attivate dagli eventi Firestore utilizzando l'emulatore. Quando gli emulatori Firestore e Cloud Functions sono entrambi in esecuzione, funzionano automaticamente insieme.
SDK di amministrazione
Gli SDK di amministrazione di Firebase si connettono automaticamente all'emulatore Cloud Firestore quando è impostata la variabile di ambiente FIRESTORE_EMULATOR_HOST :
export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"
Se il tuo codice è in esecuzione all'interno dell'emulatore Cloud Functions, l'ID progetto e altre configurazioni vengono impostati automaticamente quando si chiama initializeApp .
Se desideri che il codice dell'SDK Admin si connetta a un emulatore condiviso in esecuzione in un altro ambiente, devi specificare lo stesso ID progetto impostato utilizzando la CLI di Firebase . Puoi passare un ID progetto per initializeApp o impostare la variabile di ambiente GCLOUD_PROJECT .
SDK di amministrazione Node.js
admin.initializeApp({ projectId: "your-project-id" });
Variabile d'ambiente
export GCLOUD_PROJECT="your-project-id"
Cancella il tuo database tra un test e l'altro
Production Firestore non fornisce alcun metodo SDK della piattaforma per svuotare il database, ma l'emulatore Firestore fornisce un endpoint REST specifico per questo scopo, che può essere chiamato da un passaggio di installazione/smontaggio del framework di test, da una classe di test o dalla shell (ad esempio , con curl ) prima dell'inizio di un test. È possibile utilizzare questo approccio come alternativa al semplice arresto del processo di emulazione.
Con un metodo appropriato, esegui un'operazione HTTP DELETE, fornendo il tuo ID progetto Firebase, ad esempio firestore-emulator-example , al seguente endpoint:
"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"
Naturalmente, il tuo codice dovrebbe attendere la conferma REST che il flush è terminato o non è riuscito.
Puoi eseguire questa operazione dalla shell:
// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"
Dopo aver implementato un passaggio come questo, puoi mettere in sequenza i tuoi test e attivare le tue funzioni con la certezza che i vecchi dati verranno eliminati tra un'esecuzione e l'altra e che stai utilizzando una nuova configurazione di test di base.
Importare ed esportare dati
Il database e gli emulatori Cloud Storage for Firebase consentono di esportare dati da un'istanza dell'emulatore in esecuzione. Definisci un set di dati di base da utilizzare nei test unitari o nei flussi di lavoro di integrazione continua, quindi esportalo per condividerlo con il team.
firebase emulators:export ./dir
Nei test, all'avvio dell'emulatore, importa i dati di base.
firebase emulators:start --import=./dir
Puoi istruire l'emulatore ad esportare i dati allo spegnimento, specificando un percorso di esportazione o semplicemente utilizzando il percorso passato al flag --import .
firebase emulators:start --import=./dir --export-on-exit
Queste opzioni di importazione ed esportazione dei dati funzionano anche con il comando firebase emulators:exec . Per ulteriori informazioni, fare riferimento al riferimento ai comandi dell'emulatore .
Visualizza l'attività delle regole di sicurezza
Mentre lavori su prototipi e cicli di test, puoi utilizzare gli strumenti di visualizzazione e i report forniti da Local Emulator Suite.
Utilizzare il monitoraggio delle richieste
L'emulatore Cloud Firestore ti consente di visualizzare le richieste dei client nell'interfaccia utente di Emulator Suite, inclusa la traccia della valutazione per le regole di sicurezza Firebase.
Apri la scheda Firestore > Richieste per visualizzare la sequenza di valutazione dettagliata per ciascuna richiesta.
Visualizza i report di valutazione delle regole
Quando aggiungi regole di sicurezza al tuo prototipo puoi eseguirne il debug con gli strumenti di debug di Local Emulator Suite.
Dopo aver eseguito una serie di test, puoi accedere ai report sulla copertura dei test che mostrano come è stata valutata ciascuna delle tue regole di sicurezza.
Per ottenere i report, esegui una query su un endpoint esposto sull'emulatore mentre è in esecuzione. Per una versione ottimizzata per il browser, utilizzare il seguente URL:
http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html
Ciò suddivide le regole in espressioni e sottoespressioni su cui puoi passare il mouse per ulteriori informazioni, incluso il numero di valutazioni e valori restituiti. Per la versione JSON non elaborata di questi dati, includi il seguente URL nella query:
http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage
Qui, la versione HTML del report evidenzia le valutazioni che generano errori non definiti e con valore nullo:
Differenze tra l'emulatore Cloud Firestore e la produzione
L'emulatore Cloud Firestore tenta di replicare fedelmente il comportamento del servizio di produzione con alcune notevoli limitazioni.
Supporto di più database per Cloud Firestore
Attualmente, l'interfaccia utente di Emulator Suite supporta la creazione interattiva, la modifica, l'eliminazione, il monitoraggio delle richieste e la visualizzazione della sicurezza per un database predefinito, ma non per database denominati aggiuntivi.
Tuttavia, l'emulatore stesso crea un database denominato in base alla configurazione nel file firebase.json e implicitamente in risposta alle chiamate SDK o API REST.
Transazioni
L'emulatore attualmente non implementa tutti i comportamenti di transazione visti nella produzione. Quando si testano funzionalità che implicano più scritture simultanee su un documento, l'emulatore potrebbe essere lento nel completare le richieste di scrittura. In alcuni casi, il rilascio dei blocchi potrebbe richiedere fino a 30 secondi. Considerare la possibilità di modificare di conseguenza i timeout dei test, se necessario.
Indici
L'emulatore non tiene traccia degli indici composti ed eseguirà invece qualsiasi query valida. Assicurati di testare la tua app rispetto a un'istanza reale di Cloud Firestore per determinare quali indici ti serviranno.
Limiti
L'emulatore non applica tutti i limiti imposti nella produzione. Ad esempio, l'emulatore potrebbe consentire transazioni che verrebbero rifiutate perché troppo grandi dal servizio di produzione. Assicurati di conoscere i limiti documentati e di progettare la tua app per evitarli in modo proattivo.
E dopo?
- Per una serie curata di video ed esempi dettagliati di procedure, segui la playlist di formazione sugli emulatori Firebase .
- Esamina i casi d'uso avanzati che coinvolgono il test delle regole di sicurezza e l'SDK di test Firebase: Test Security Rules (Firestore) .
- Poiché le funzioni attivate rappresentano una tipica integrazione con Cloud Firestore, scopri di più sull'emulatore Cloud Functions for Firebase nella sezione Esegui funzioni localmente .