Connetti la tua app all'emulatore di Cloud Firestore

Prima di connettere l'app all'emulatore di Cloud Firestore, assicurati di aver compreso il flusso di lavoro generale 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 di un singolo progetto Firebase.

Per selezionare il progetto da utilizzare, prima di avviare gli emulatori, esegui nell'interfaccia a riga di comando firebase use nella tua directory di lavoro. In alternativa, puoi passare il flag --project a ciascun comando dell'emulatore.

Local Emulator Suite supporta l'emulazione di progetti Firebase e demo reali.

Ti consigliamo di utilizzare progetti dimostrativi quando possibile. I vantaggi includono:

• Configurazione più semplice, dato che puoi eseguire gli emulatori senza dover creare un progetto Firebase
• Maggiore sicurezza perché se il codice richiama accidentalmente risorse non emulate (produzione), non sussiste alcuna possibilità di modifica, utilizzo e fatturazione dei dati
• Supporto offline migliorato, dato che non è necessario accedere a internet per scaricare la configurazione dell'SDK.

Usa gli strumenti per comunicare con gli emulatori

All'avvio, l'emulatore Cloud Firestore crea un database predefinito e un database denominato per ogni configurazione firestore nel tuo file firebase.json.

I database denominati vengono inoltre creati implicitamente in risposta a qualsiasi chiamata API SDK o REST all'emulatore che faccia riferimento a un database specifico. Questi database creati implicitamente utilizzano regole aperte.

Per lavorare con i tuoi database predefiniti e denominati in modo interattivo nell'interfaccia utente di Emulator Suite, aggiorna l'URL nella barra degli indirizzi del browser per selezionare il database predefinito o denominato.

• Ad esempio, per sfogliare i dati nell'istanza predefinita, aggiorna l'URL in localhost:4000/firestore/default/data
• Per navigare in un'istanza denominata ecommerce, esegui l'aggiornamento a localhost:4000/firestore/ecommerce/data.

Android, piattaforme Apple e SDK web

Imposta la configurazione in-app o le classi di test per interagire con Cloud Firestore come segue. Tieni presente che negli esempi riportati di seguito il codice dell'app si connette al database di progetto predefinito. Per esempi relativi ad altri database Cloud Firestore oltre al database predefinito, consulta la guida per più database.

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

Non è necessaria alcuna configurazione aggiuntiva per testare le funzioni Cloud Functions attivate dagli eventi Firestore utilizzando l'emulatore. Quando gli emulatori di Firestore e Cloud Functions sono in esecuzione, funzionano automaticamente insieme.

SDK amministrativi

Gli SDK Firebase Admin si connettono automaticamente all'emulatore Cloud Firestore quando la variabile di ambiente FIRESTORE_EMULATOR_HOST è impostata:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Se il tuo codice viene eseguito nell'emulatore Cloud Functions, il tuo ID progetto e altre configurazioni vengono impostati automaticamente quando chiami initializeApp.

Se vuoi che il codice SDK Admin si connetta a un emulatore condiviso in esecuzione in un altro ambiente, devi specificare lo stesso ID progetto che hai impostato utilizzando l'interfaccia a riga di comando di Firebase. Puoi passare un ID progetto direttamente a initializeApp o impostare la variabile di ambiente GCLOUD_PROJECT.

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

export GCLOUD_PROJECT="your-project-id"

Cancella il database tra un test e l'altro

Firestore di produzione non fornisce un metodo SDK della piattaforma per eseguire lo svuotamento del database, ma l'emulatore Firestore ti fornisce un endpoint REST specifico per questo scopo, che può essere chiamato da un passaggio di configurazione del framework di test/tearDown, da una classe di test o dalla shell (ad esempio, con curl) prima dell'avvio di un test. Puoi utilizzare questo approccio come alternativa alla semplice arresto del processo dell'emulatore.

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 codice dovrebbe attendere la conferma da parte di REST che lo svuotamento sia terminato o non sia 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 di questo tipo, puoi sequenza i test e attivare le funzioni con la certezza che i vecchi dati verranno eliminati definitivamente tra le esecuzioni e l'utilizzo di una nuova configurazione di test di base.

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 delle unità o nei flussi di lavoro di integrazione continua, quindi esportalo in modo che venga condiviso 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 quello trasmesso 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 la documentazione di riferimento dei comandi dell'emulatore.

Visualizza l'attività Regole di sicurezza

Durante l'elaborazione di prototipi e loop di test, puoi utilizzare gli strumenti di visualizzazione e i report forniti da Local Emulator Suite.

Utilizzare il monitoraggio delle richieste

L'emulatore di Cloud Firestore ti consente di visualizzare le richieste dei client nell'interfaccia utente di Emulator Suite, incluso il tracciamento di valutazione per le regole di sicurezza di Firebase.

Apri la scheda Firestore > Richieste per visualizzare la sequenza di valutazione dettagliata per ogni richiesta.

Visualizzare 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 suite di test, puoi accedere ai report sulla copertura di test che mostrano come è stata valutata ciascuna delle tue regole di sicurezza.

Per ottenere i report, esegui una query su un endpoint esposto nell'emulatore mentre è in esecuzione. Per una versione ottimizzata per il 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 passare il mouse per 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

In questo caso, la versione HTML del report evidenzia le valutazioni che generano errori con valori non definiti e con valori null:

Differenze tra l'emulatore di Cloud Firestore e la produzione

L'emulatore di Cloud Firestore tenta di replicare fedelmente il comportamento del servizio di produzione con alcune limitazioni degne di nota.

Supporto di più database per Cloud Firestore

Attualmente, la UI 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 crea un database denominato in base alla configurazione nel file firebase.json e implicitamente in risposta alle chiamate API REST e SDK.

Transazioni

L'emulatore al momento non implementa tutti i comportamenti di transazione previsti in produzione. Quando stai testando funzionalità che prevedono più scritture simultanee in un documento, l'emulatore potrebbe essere lento a completare le richieste di scrittura. In alcuni casi, il rilascio 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 ed esegue invece qualsiasi query valida. Assicurati di testare l'app su un'istanza di Cloud Firestore reale per determinare gli indici di cui hai bisogno.

Limiti

L'emulatore non applica tutti i limiti applicati in produzione. Ad esempio, l'emulatore potrebbe consentire transazioni che verrebbero rifiutate dal servizio di produzione in quanto troppo grandi. Assicurati di conoscere i limiti documentati e di progettare la tua app per evitarli in modo proattivo.

E adesso?

• Per un insieme selezionato di video ed esempi di istruzioni dettagliati, segui la playlist di formazione sugli emulatori di Firebase.
• Esamina i casi d'uso avanzati che includono il test delle regole di sicurezza e l'SDK Firebase Test: Test Security Rules (Firestore).
• Poiché le funzioni attivate sono un'integrazione tipica con Cloud Firestore, scopri di più sull'emulatore di Cloud Functions for Firebase in Eseguire le funzioni localmente.