Prima di collegare l'app all'emulatore Cloud Firestore, assicurati di comprendere il flusso di lavoro complessivo di Firebase Local Emulator Suite, di installare e configurare Local Emulator Suite e di esaminare i relativi comandi CLI.
Scegli un progetto Firebase
Firebase Local Emulator Suite emula i prodotti per un singolo progetto Firebase.
Per selezionare il progetto da utilizzare, prima di avviare gli emulatori, esegui firebase use
nella directory di lavoro in CLI. In alternativa, puoi passare il flag --project
a ogni comando dell'emulatore.
Local Emulator Suite supporta l'emulazione di progetti Firebase reali e progetti dimostrativi.
Tipo di progetto | Funzionalità | Utilizzo con emulatori |
---|---|---|
Reale |
Un progetto Firebase reale è 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 il 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 in produzione (istanza di database, bucket di archiviazione, funzione e così via). |
Demo |
Un progetto Firebase dimostrativo non ha una configurazione Firebase reale e non ha risorse attive. In genere, si accede a questi progetti tramite codelab o altri tutorial. Gli ID progetto per i progetti demo hanno il prefisso |
Quando utilizzi progetti Firebase di prova, 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 non andrà a buon fine. |
Ti consigliamo di utilizzare progetti demo, se possibile. I vantaggi includono:
- Configurazione più semplice, poiché puoi eseguire gli emulatori senza dover creare un progetto Firebase
- Maggiore sicurezza, poiché se il codice richiama accidentalmente risorse non emulate (di produzione), non c'è alcuna possibilità di modifica, utilizzo e fatturazione dei dati
- Migliore assistenza offline, poiché non è necessario accedere a internet per scaricare la configurazione dell'SDK.
Instrumenta l'app in modo che possa 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
.
I database denominati vengono creati anche in modo implicito in risposta a qualsiasi chiamata SDK o API REST all'emulatore che fa riferimento a un database specifico. Questi database creati implicitamente funzionano con regole aperte.
Per lavorare in modo interattivo con i database predefiniti e con nome in Emulator Suite UI, aggiorna l'URL nella barra degli indirizzi del browser per selezionare il database predefinito o un database denominato.
- Ad esempio, per sfogliare i dati nell'istanza predefinita, aggiorna l'URL su
localhost:4000/firestore/default/data
- Per sfogliare un'istanza denominata
ecommerce
, esegui l'aggiornamento alocalhost:4000/firestore/ecommerce/data
.
Android, piattaforme Apple e SDK web
Configura la configurazione in-app o i test di classe per interagire con Cloud Firestore come segue. Tieni presente che nei seguenti esempi il codice dell'app si connette al database del progetto predefinito. Per esempi che coinvolgono database Cloud Firestore aggiuntivi oltre a quello predefinito, consulta la 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);
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); }
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.
Admin SDK s
I Firebase Admin SDK 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 codice viene eseguito all'interno dell'emulatore Cloud Functions, l'ID progetto
e altre configurazioni vengono impostati automaticamente quando chiami initializeApp
.
Se vuoi che il codice Admin SDK si connetta a un emulatore condiviso in un altro ambiente, devi specificare lo stesso ID progetto impostato utilizzando Firebase CLI.
Puoi passare un ID progetto direttamente a initializeApp
o impostare la variabile di ambiente GCLOUD_PROJECT
.
SDK Node.js Admin
admin.initializeApp({ projectId: "your-project-id" });
Variabile di ambiente
export GCLOUD_PROJECT="your-project-id"
Svuotare il database tra un test e l'altro
Firestore di produzione non fornisce alcun metodo SDK di piattaforma per svuotare il database, ma l'emulatore Firestore fornisce un endpoint REST appositamente per questo scopo, che può essere chiamato da un passaggio di configurazione/tearDown del framework di test, da una classe di test o dalla shell (ad es. con curl
) prima dell'avvio di un test. Puoi utilizzare questo approccio come alternativa alla semplice chiusura del processo dell'emulatore.
In 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 codice deve attendere la conferma REST che l'operazione di svuotamento è stata completata o non è riuscita.
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 sequenziare i test e attivare le funzioni con la certezza che i vecchi dati verranno eliminati tra un'esecuzione e l'altra e che utilizzi una nuova configurazione di test di riferimento.
Importazione ed esportazione di dati
Gli emulatori di database e Cloud Storage for Firebase ti consentono di esportare i dati da un'istanza di emulatore in esecuzione. Definisci un set di dati di riferimento da utilizzare nei test di unità 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 riferimento.
firebase emulators:start --import=./dir
Puoi indicare all'emulatore di esportare i dati all'arresto, 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 saperne di più, consulta il riferimento ai comandi dell'emulatore.
Visualizzare l'attività delle regole di sicurezza
Man mano che esegui i loop di test e di creazione di prototipi, puoi utilizzare gli strumenti di visualizzazione e i report forniti da Local Emulator Suite.
Utilizzare Monitor richieste
L'emulatore Cloud Firestore ti consente di visualizzare le richieste del client nel Emulator Suite UI, incluso il monitoraggio della valutazione per Firebase Security Rules.
Apri la scheda Firestore > Richieste per visualizzare la sequenza di valutazione dettagliata per ogni richiesta.
Visualizzare i report Valutazione delle regole
Man mano che aggiungi regole di sicurezza al tuo prototipo, puoi eseguire il debug con gli strumenti di debug Local Emulator Suite.
Dopo aver eseguito una suite di test, puoi accedere ai report sulla copertura dei test che mostrano in che modo è 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 adatta ai browser, utilizza il seguente URL:
http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html
In questo modo, le regole vengono suddivise in espressioni e sottoespressioni su cui puoi eseguire il passaggio del mouse per visualizzare ulteriori informazioni, tra cui il numero di valutazioni e i 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 di valori null e non definiti:
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 limitazioni significative.
Supporto di più database per Cloud Firestore
Attualmente, Emulator Suite UI supporta la creazione, la modifica, l'eliminazione, il monitoraggio delle richieste e la visualizzazione della sicurezza interattiva per un database predefinito, ma non per altri database denominati.
Tuttavia, l'emulatore stesso crea un database denominato in base alla configurazione nel file firebase.json
e implicitamente in risposta alle chiamate dell'SDK o dell'API REST.
Transazioni
Al momento l'emulatore non implementa tutto il comportamento delle transazioni riscontrato in produzione. Quando testi funzionalità che richiedono più scrittura contemporaneamente in un documento, l'emulatore potrebbe essere lento a completare le richieste di scrittura. In alcuni casi, la disattivazione delle serrature può richiedere fino a 30 secondi. Se necessario, valuta la possibilità di modificare di conseguenza i timeout dei test.
Indici
L'emulatore non monitora gli indici composti, ma eseguirà qualsiasi query valida. Assicurati di testare l'app su un'istanza Cloud Firestore reale per determinare quali indici ti serviranno.
Limiti
L'emulatore non applica tutti i limiti applicati in produzione. Ad esempio, l'emulatore potrebbe consentire transazioni che verrebbero rifiutate come troppo grandi dal servizio di produzione. Assicurati di conoscere i limiti documentati e di progettare l'app in modo da evitarli in modo proattivo.
Che cosa succede ora?
- Per una raccolta selezionata di video ed esempi pratici dettagliati, consulta la playlist di formazione su Firebase Emulators.
- Esamina casi d'uso avanzati che coinvolgono i test delle regole di sicurezza e l'SDK di test Firebase: Test delle regole di sicurezza (Firestore).
- Poiché le funzioni attivate sono un'integrazione tipica con Cloud Firestore, scopri di più sull'emulatore Cloud Functions for Firebase in Eseguire funzioni localmente.