Sviluppo locale con Firebase Emulator Suite

1. Prima di iniziare

Gli strumenti di backend serverless come Cloud Firestore e Cloud Functions sono molto facili da usare, ma possono essere difficili da testare. Firebase Local Emulator Suite ti consente di eseguire versioni locali di questi servizi sul tuo computer di sviluppo in modo da poter sviluppare la tua app in modo rapido e sicuro.

Prerequisiti

• Un semplice editor come Visual Studio Code, Atom o Sublime Text
• Node.js 10.0.0 o versioni successive (per installare Node.js, usa nvm , per verificare la tua versione, esegui node --version )
• Java 7 o versioni successive (per installare Java utilizzare queste istruzioni , per verificare la versione, eseguire java -version )

Cosa farai

In questo codelab, eseguirai ed eseguirai il debug di una semplice app per lo shopping online basata su più servizi Firebase:

• Cloud Firestore: un database NoSQL scalabile a livello globale, senza server, con funzionalità in tempo reale.
• Funzioni cloud : un codice di backend serverless che viene eseguito in risposta a eventi o richieste HTTP.
• Firebase Authentication : un servizio di autenticazione gestito che si integra con altri prodotti Firebase.
• Firebase Hosting : hosting veloce e sicuro per le app web.

Connetterai l'app a Emulator Suite per abilitare lo sviluppo locale.

Imparerai anche a:

• Come connettere la tua app alla Emulator Suite e come sono collegati i vari emulatori.
• Come funzionano le regole di sicurezza di Firebase e come testare le regole di sicurezza di Firestore rispetto a un emulatore locale.
• Come scrivere una funzione Firebase attivata da eventi Firestore e come scrivere test di integrazione che vengono eseguiti su Emulator Suite.

2. Configurare

Ottieni il codice sorgente

In questo codelab, inizi con una versione dell'esempio di The Fire Store che è quasi completa, quindi la prima cosa che devi fare è clonare il codice sorgente:

$ git clone https://github.com/firebase/emulators-codelab.git

Quindi spostati nella directory del codelab, dove lavorerai per il resto di questo codelab:

$ cd emulators-codelab/codelab-initial-state

Ora installa le dipendenze in modo da poter eseguire il codice. Se utilizzi una connessione Internet più lenta, potrebbero essere necessari uno o due minuti:

# Move into the functions directory
$ cd functions

# Install dependencies
$ npm install

# Move back into the previous directory
$ cd ../

Ottieni l'interfaccia a riga di comando di Firebase

Emulator Suite fa parte della Firebase CLI (interfaccia della riga di comando) che può essere installata sul tuo computer con il seguente comando:

$ npm install -g firebase-tools

Successivamente, conferma di disporre dell'ultima versione dell'interfaccia a riga di comando. Questo codelab dovrebbe funzionare con la versione 9.0.0 o successiva, ma le versioni successive includono più correzioni di bug.

$ firebase --version
9.6.0

Connettiti al tuo progetto Firebase

Se non disponi di un progetto Firebase, nella console Firebase crea un nuovo progetto Firebase. Prendi nota dell'ID progetto che scegli, ti servirà in seguito.

Ora dobbiamo collegare questo codice al tuo progetto Firebase. Per prima cosa esegui il seguente comando per accedere alla CLI di Firebase:

$ firebase login

Eseguire quindi il comando seguente per creare un alias di progetto. Sostituisci $YOUR_PROJECT_ID con l'ID del tuo progetto Firebase.

$ firebase use $YOUR_PROJECT_ID

Ora sei pronto per eseguire l'app!

3. Eseguire gli emulatori

In questa sezione, eseguirai l'app in locale. Ciò significa che è ora di avviare Emulator Suite.

Avvia gli emulatori

Dall'interno della directory dei sorgenti del codelab, esegui il seguente comando per avviare gli emulatori:

$ firebase emulators:start --import=./seed

Dovresti vedere un output come questo:

$ firebase emulators:start --import=./seed
i  emulators: Starting emulators: auth, functions, firestore, hosting
⚠  functions: The following emulators are not running, calls to these services from the Functions emulator will affect production: database, pubsub
i  firestore: Importing data from /Users/samstern/Projects/emulators-codelab/codelab-initial-state/seed/firestore_export/firestore_export.overall_export_metadata
i  firestore: Firestore Emulator logging to firestore-debug.log
i  hosting: Serving hosting files from: public
✔  hosting: Local server: http://127.0.0.1:5000
i  ui: Emulator UI logging to ui-debug.log
i  functions: Watching "/Users/samstern/Projects/emulators-codelab/codelab-initial-state/functions" for Cloud Functions...
✔  functions[calculateCart]: firestore function initialized.

┌─────────────────────────────────────────────────────────────┐
│ ✔  All emulators ready! It is now safe to connect your app. │
│ i  View Emulator UI at http://127.0.0.1:4000                │
└─────────────────────────────────────────────────────────────┘

┌────────────────┬────────────────┬─────────────────────────────────┐
│ Emulator       │ Host:Port      │ View in Emulator UI             │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Authentication │ 127.0.0.1:9099 │ http://127.0.0.1:4000/auth      │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Functions      │ 127.0.0.1:5001 │ http://127.0.0.1:4000/functions │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Firestore      │ 127.0.0.1:8080 │ http://127.0.0.1:4000/firestore │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Hosting        │ 127.0.0.1:5000 │ n/a                             │
└────────────────┴────────────────┴─────────────────────────────────┘
  Emulator Hub running at 127.0.0.1:4400
  Other reserved ports: 4500

Issues? Report them at https://github.com/firebase/firebase-tools/issues and attach the *-debug.log files.

Una volta visualizzato il messaggio Tutti gli emulatori avviati , l'app è pronta per l'uso.

A parte: cosa è appena successo?

• Ogni emulatore è stato avviato su 127.0.0.1, ognuno è in esecuzione su una porta diversa.
• L'emulatore Firestore ha importato i dati dalla directory seed , fornita per semplificare questo codelab.
• L'emulatore di funzioni ha notato la calculateCart e ha notificato l'emulatore Firestore.
• L'emulatore di funzioni ora controlla la directory functions per le modifiche al codice.

Connetti l'app Web agli emulatori

Sulla base della tabella nei log possiamo vedere che l'emulatore Cloud Firestore è in ascolto sulla porta 8080 e l'emulatore di autenticazione è in ascolto sulla porta 9099 .

┌────────────────┬────────────────┬─────────────────────────────────┐
│ Emulator       │ Host:Port      │ View in Emulator UI             │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Authentication │ 127.0.0.1:9099 │ http://127.0.0.1:4000/auth      │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Functions      │ 127.0.0.1:5001 │ http://127.0.0.1:4000/functions │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Firestore      │ 127.0.0.1:8080 │ http://127.0.0.1:4000/firestore │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Hosting        │ 127.0.0.1:5000 │ n/a                             │
└────────────────┴────────────────┴─────────────────────────────────┘

Colleghiamo il tuo codice frontend all'emulatore, piuttosto che alla produzione. Apri il file public/js/homepage.js e trova la funzione onDocumentReady . Possiamo vedere che il codice accede alle istanze Firestore e Auth standard:

public/js/homepage.js

  const auth = firebaseApp.auth();
  const db = firebaseApp.firestore();

Aggiorniamo gli oggetti db e auth in modo che puntino agli emulatori locali:

public/js/homepage.js

  const auth = firebaseApp.auth();
  const db = firebaseApp.firestore();

  // ADD THESE LINES
  if (location.hostname === "127.0.0.1") {
    console.log("127.0.0.1 detected!");
    auth.useEmulator("http://127.0.0.1:9099");
    db.useEmulator("127.0.0.1", 8080);
  }

Ora, quando l'app è in esecuzione sul tuo computer locale (servito dall'emulatore di hosting), il client Firestore punta anche all'emulatore locale anziché a un database di produzione.

Apri l'interfaccia utente dell'emulatore

Nel tuo browser web, vai a http://127.0.0.1:4000/ . Dovresti vedere l'interfaccia utente di Emulator Suite.

Fai clic per visualizzare l'interfaccia utente dell'emulatore Firestore. La raccolta items contiene già dati a causa dei dati importati con il flag --import .

4. Eseguire l'app

Apri l'app

Nel tuo browser web, vai su http://127.0.0.1:5000 e dovresti vedere The Fire Store in esecuzione localmente sul tuo computer!

Usa l'app

Scegli un articolo sulla home page e fai clic su Aggiungi al carrello . Sfortunatamente, ti imbatterai nel seguente errore:

Risolviamo quel bug! Poiché tutto è in esecuzione negli emulatori, possiamo sperimentare e non preoccuparci di influire sui dati reali.

5. Eseguire il debug dell'app

Trova il bug

Ok, diamo un'occhiata alla console per sviluppatori di Chrome. Premi Control+Shift+J (Windows, Linux, Chrome OS) o Command+Option+J (Mac) per visualizzare l'errore sulla console:

Sembra che ci sia stato qualche errore nel metodo addToCart , diamo un'occhiata. Dove proviamo ad accedere a qualcosa chiamato uid in quel metodo e perché dovrebbe essere null ? In questo momento il metodo è simile a questo in public/js/homepage.js :

public/js/homepage.js

  addToCart(id, itemData) {
    console.log("addToCart", id, JSON.stringify(itemData));
    return this.db
      .collection("carts")
      .doc(this.auth.currentUser.uid)
      .collection("items")
      .doc(id)
      .set(itemData);
  }

Ah! Non abbiamo effettuato l'accesso all'app. Secondo i documenti di Firebase Authentication , quando non si è effettuato l'accesso, auth.currentUser è null . Aggiungiamo un controllo per questo:

public/js/homepage.js

  addToCart(id, itemData) {
    // ADD THESE LINES
    if (this.auth.currentUser === null) {
      this.showError("You must be signed in!");
      return;
    }

    // ...
  }

Prova l'app

Ora aggiorna la pagina e fai clic su Aggiungi al carrello . Questa volta dovresti ottenere un errore migliore:

Ma se fai clic su Accedi nella barra degli strumenti in alto e poi fai di nuovo clic su Aggiungi al carrello , vedrai che il carrello viene aggiornato.

Nota : a scopo dimostrativo, questa applicazione utilizza esclusivamente l'autenticazione anonima . Anonymous Auth assegna a ciascun utente di sessione un ID che lo identifica in modo univoco nel back-end. Ti consente di creare un'esperienza di onboarding che non richiede agli utenti di creare immediatamente un account permanente. Nelle applicazioni di produzione, per salvare i dati utente tra sessioni e dispositivi, dovrai convertire gli utenti da Anonymous Auth a un altro metodo di accesso.

Tuttavia, non sembra affatto che i numeri siano corretti:

Non preoccuparti, risolveremo presto il bug. Per prima cosa, approfondiamo ciò che è realmente accaduto quando hai aggiunto un articolo al carrello.

6. Trigger di funzioni locali

Facendo clic su Aggiungi al carrello si avvia una catena di eventi che coinvolge più emulatori. Nei log dell'interfaccia a riga di comando di Firebase, dovresti visualizzare qualcosa di simile ai seguenti messaggi dopo aver aggiunto un articolo al carrello:

i  functions: Beginning execution of "calculateCart"
i  functions: Finished "calculateCart" in ~1s

Ci sono stati quattro eventi chiave che si sono verificati per produrre quei registri e l'aggiornamento dell'interfaccia utente che hai osservato:

Nota : non è necessario aggiornare l'app con gli snippet di codice riportati di seguito. Il codice è già incluso nell'app. I frammenti di codice in questa sezione vengono presentati solo per aiutarti a comprendere i quattro eventi chiave.

1) Scrittura Firestore - Cliente

Un nuovo documento viene aggiunto alla raccolta Firestore /carts/{cartId}/items/{itemId}/ . Puoi vedere questo codice nella funzione addToCart all'interno di public/js/homepage.js :

public/js/homepage.js

  addToCart(id, itemData) {
    // ...
    console.log("addToCart", id, JSON.stringify(itemData));
    return this.db
      .collection("carts")
      .doc(this.auth.currentUser.uid)
      .collection("items")
      .doc(id)
      .set(itemData);
  }

2) Funzione cloud attivata

La funzione calculateCart ascolta eventuali eventi di scrittura (creazione, aggiornamento o eliminazione) che si verificano sugli articoli del carrello utilizzando il trigger onWrite , che puoi vedere in functions/index.js :

funzioni/index.js

exports.calculateCart = functions.firestore
    .document("carts/{cartId}/items/{itemId}")
    .onWrite(async (change, context) => {
      try {
        let totalPrice = 125.98;
        let itemCount = 8;

        const cartRef = db.collection("carts").doc(context.params.cartId);

        await cartRef.update({
          totalPrice,
          itemCount
        });
      } catch(err) {
      }
    }
);

3) Scrittura Firestore - Amministratore

La funzione calculateCart legge tutti gli articoli nel carrello e somma la quantità totale e il prezzo, quindi aggiorna il documento "carrello" con i nuovi totali (vedi cartRef.update(...) sopra).

4) Lettura Firestore - Cliente

Il frontend web è sottoscritto per ricevere aggiornamenti sulle modifiche al carrello. Ottiene un aggiornamento in tempo reale dopo che la Funzione Cloud scrive i nuovi totali e aggiorna l'interfaccia utente, come puoi vedere in public/js/homepage.js :

public/js/homepage.js

this.cartUnsub = cartRef.onSnapshot(cart => {
   // The cart document was changed, update the UI
   // ...
});

Ricapitolare

Bel lavoro! Hai appena configurato un'app completamente locale che utilizza tre diversi emulatori Firebase per i test completamente locali.

Ma aspetta, c'è di più! Nella prossima sezione imparerai:

• Come scrivere unit test che utilizzano gli emulatori Firebase.
• Come utilizzare gli emulatori Firebase per eseguire il debug delle regole di sicurezza.

7. Crea regole di sicurezza su misura per la tua app

La nostra app Web legge e scrive dati, ma finora non ci siamo preoccupati affatto della sicurezza. Cloud Firestore utilizza un sistema chiamato "Regole di sicurezza" per dichiarare chi ha accesso ai dati in lettura e scrittura. Emulator Suite è un ottimo modo per prototipare queste regole.

Nell'editor, apri il file emulators-codelab/codelab-initial-state/firestore.rules . Vedrai che abbiamo tre sezioni principali nelle nostre regole:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // User's cart metadata
    match /carts/{cartID} {
      // TODO: Change these! Anyone can read or write.
      allow read, write: if true;
    }

    // Items inside the user's cart
    match /carts/{cartID}/items/{itemID} {
      // TODO: Change these! Anyone can read or write.
      allow read, write: if true;
    }

    // All items available in the store. Users can read
    // items but never write them.
    match /items/{itemID} {
      allow read: if true;
    }
  }
}

In questo momento chiunque può leggere e scrivere dati nel nostro database! Vogliamo assicurarci che passino solo operazioni valide e che non trapeliamo informazioni sensibili.

Durante questo codelab, seguendo il principio del privilegio minimo, bloccheremo tutti i documenti e aggiungeremo gradualmente l'accesso fino a quando tutti gli utenti avranno tutto l'accesso di cui hanno bisogno, ma non di più. Aggiorniamo le prime due regole per negare l'accesso impostando la condizione su false :

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // User's cart metadata
    match /carts/{cartID} {
      // UPDATE THIS LINE
      allow read, write: if false;
    }

    // Items inside the user's cart
    match /carts/{cartID}/items/{itemID} {
      // UPDATE THIS LINE
      allow read, write: if false;
    }

    // All items available in the store. Users can read
    // items but never write them.
    match /items/{itemID} {
      allow read: if true;
    }
  }
}

A parte: cosa succede se non ci sono dichiarazioni di corrispondenza per un'operazione?

• Le regole negano per impostazione predefinita. Se un'operazione non corrisponde a nessuna regola definita nel file delle regole, l'accesso verrà negato.
• La modalità bloccata, o modalità di produzione, trasforma quella negazione implicita in una negazione esplicita abbinando tutti i documenti e negando ogni accesso.

8. Eseguire gli emulatori ei test

Avvia gli emulatori

Sulla riga di comando, assicurati di essere in emulators-codelab/codelab-initial-state/ . Potresti avere ancora gli emulatori in esecuzione dai passaggi precedenti. In caso contrario, riavvia gli emulatori:

$ firebase emulators:start --import=./seed

Una volta che gli emulatori sono in esecuzione, puoi eseguire i test localmente su di essi.

Eseguire i test

Sulla riga di comando in una nuova scheda del terminale dalla directory emulators-codelab/codelab-initial-state/

Per prima cosa spostati nella directory functions (rimarremo qui per il resto del codelab):

$ cd functions

Ora esegui i test mocha nella directory functions e scorri fino all'inizio dell'output:

# Run the tests
$ npm test

> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha

  shopping carts
    1) can be created and updated by the cart owner
    2) can be read only by the cart owner

  shopping cart items
    3) can be read only by the cart owner
    4) can be added only by the cart owner

  adding an item to the cart recalculates the cart total. 
    - should sum the cost of their items


  0 passing (364ms)
  1 pending
  4 failing

In questo momento abbiamo quattro fallimenti. Mentre crei il file delle regole, puoi misurare i progressi osservando il superamento di più test.

9. Accesso sicuro al carrello

I primi due fallimenti sono i test del "carrello della spesa" che verificano che:

• Gli utenti possono solo creare e aggiornare i propri carrelli
• Gli utenti possono solo leggere i propri carrelli

funzioni/test.js

  it('can be created and updated by the cart owner', async () => {
    // Alice can create her own cart
    await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart").set({
      ownerUID: "alice",
      total: 0
    }));

    // Bob can't create Alice's cart
    await firebase.assertFails(bobDb.doc("carts/alicesCart").set({
      ownerUID: "alice",
      total: 0
    }));

    // Alice can update her own cart with a new total
    await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart").update({
      total: 1
    }));

    // Bob can't update Alice's cart with a new total
    await firebase.assertFails(bobDb.doc("carts/alicesCart").update({
      total: 1
    }));
  });

  it("can be read only by the cart owner", async () => {
    // Setup: Create Alice's cart as admin
    await admin.doc("carts/alicesCart").set({
      ownerUID: "alice",
      total: 0
    });

    // Alice can read her own cart
    await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart").get());

    // Bob can't read Alice's cart
    await firebase.assertFails(bobDb.doc("carts/alicesCart").get());
  });

Facciamo passare questi test. Nell'editor, apri il file delle regole di sicurezza, firestore.rules e aggiorna le istruzioni all'interno di match /carts/{cartID} :

firestore.rules

rules_version = '2';
service cloud.firestore {
    // UPDATE THESE LINES
    match /carts/{cartID} {
      allow create: if request.auth.uid == request.resource.data.ownerUID;
      allow read, update, delete: if request.auth.uid == resource.data.ownerUID;
    }

    // ...
  }
}

Queste regole ora consentono solo l'accesso in lettura e scrittura da parte del proprietario del carrello.

Per verificare i dati in entrata e l'autenticazione dell'utente, utilizziamo due oggetti disponibili nel contesto di ogni regola:

• L'oggetto request contiene dati e metadati sull'operazione che si sta tentando.
• Se un progetto Firebase utilizza Firebase Authentication , l'oggetto request.auth descrive l'utente che sta effettuando la richiesta.

Quali sono le principali differenze tra resource e request.resource ****?

• resource : rappresenta il documento Firestore in questione prima della richiesta corrente. Quindi, per una richiesta di creazione , resource.data è sempre null perché il documento non esiste ancora.
• request.resource : rappresenta il documento Firestore con le modifiche che l'utente vuole scrivere. Quindi, per una richiesta di creazione , request.resource.data contiene il documento proposto.

10. Testare l'accesso al carrello

Emulator Suite aggiorna automaticamente le regole ogni volta che firestore.rules viene salvato. Puoi confermare che l'emulatore ha aggiornato le regole cercando nella scheda che esegue l'emulatore per il messaggio Rules updated :

Riesegui i test e controlla che i primi due test ora passino:

$ npm test

> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha

  shopping carts
    ✓ can be created and updated by the cart owner (195ms)
    ✓ can be read only by the cart owner (136ms)

  shopping cart items
    1) can be read only by the cart owner
    2) can be added only by the cart owner

  adding an item to the cart recalculates the cart total. 
    - should sum the cost of their items

  2 passing (482ms)
  1 pending
  2 failing

Buon lavoro! Ora hai accesso sicuro ai carrelli della spesa. Passiamo al prossimo test negativo.

11. Controlla il flusso "Aggiungi al carrello" nell'interfaccia utente

Al momento, anche se i proprietari del carrello leggono e scrivono nel carrello, non possono leggere o scrivere singoli articoli nel carrello. Questo perché mentre i proprietari hanno accesso al documento del carrello, non hanno accesso alla sottoraccolta di articoli del carrello .

A parte: le regole non si sovrappongono alle sottoraccolte

• Per impostazione predefinita, le regole per un documento non si applicano ai documenti in una sottoraccolta.
• È comune desiderare regole leggermente diverse per i documenti in una sottoraccolta.
• Se vuoi che i documenti in una sottoraccolta abbiano esattamente le stesse regole, puoi usare la sintassi glob per abbinare tutti i documenti in modo ricorsivo: match /{cartId=**} (fai attenzione).

Questo è uno stato interrotto per gli utenti.

Torna all'interfaccia utente web, che è in esecuzione su http://127.0.0.1:5000, e prova ad aggiungere qualcosa al tuo carrello. Viene visualizzato un errore Permission Denied , visibile dalla console di debug, perché non abbiamo ancora concesso agli utenti l'accesso ai documenti creati nella sottoraccolta items .

12. Consenti l'accesso agli articoli del carrello

Questi due test confermano che gli utenti possono solo aggiungere articoli o leggere articoli dal proprio carrello:

  it("can be read only by the cart owner", async () => {
    // Alice can read items in her own cart
    await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart/items/milk").get());

    // Bob can't read items in alice's cart
    await firebase.assertFails(bobDb.doc("carts/alicesCart/items/milk").get())
  });

  it("can be added only by the cart owner",  async () => {
    // Alice can add an item to her own cart
    await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart/items/lemon").set({
      name: "lemon",
      price: 0.99
    }));

    // Bob can't add an item to alice's cart
    await firebase.assertFails(bobDb.doc("carts/alicesCart/items/lemon").set({
      name: "lemon",
      price: 0.99
    }));
  });

Quindi possiamo scrivere una regola che consenta l'accesso se l'utente corrente ha lo stesso UID dell'ownerUID sul documento del carrello. Poiché non è necessario specificare regole diverse per create, update, delete , è possibile utilizzare una regola write , che si applica a tutte le richieste che modificano i dati.

Aggiorna la regola per i documenti nella sottoraccolta elementi. Il get nel condizionale sta leggendo un valore da Firestore, in questo caso, l' ownerUID sul documento del carrello.

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // ...

    // UPDATE THESE LINES
    match /carts/{cartID}/items/{itemID} {
      allow read, write: if get(/databases/$(database)/documents/carts/$(cartID)).data.ownerUID == request.auth.uid;
    }

    // ...
  }
}

A parte: quando puoi utilizzare una risorsa o effettuare una chiamata di ricezione?

• È possibile utilizzare l'oggetto resource quando i dati richiesti fanno parte del documento corrente in fase di lettura/scrittura.
• Se hai bisogno di dati al di fuori del documento corrente, usa un'istruzione get . Tieni presente che queste operazioni vengono conteggiate nella fattura di Firestore!

13. Testare l'accesso agli articoli del carrello

Ora possiamo ripetere il test. Scorri fino all'inizio dell'output e verifica che vengano superati più test:

$ npm test

> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha

  shopping carts
    ✓ can be created and updated by the cart owner (195ms)
    ✓ can be read only by the cart owner (136ms)

  shopping cart items
    ✓ can be read only by the cart owner (111ms)
    ✓ can be added only by the cart owner


  adding an item to the cart recalculates the cart total. 
    - should sum the cost of their items


  4 passing (401ms)
  1 pending

Carino! Ora tutti i nostri test passano. Abbiamo un test in sospeso, ma ci arriveremo in pochi passaggi.

14. Controlla di nuovo il flusso "aggiungi al carrello".

Torna al front-end Web ( http://127.0.0.1:5000 ) e aggiungi un articolo al carrello. Questo è un passo importante per confermare che i nostri test e le nostre regole corrispondono alla funzionalità richiesta dal cliente. (Ricorda che l'ultima volta che abbiamo provato l'interfaccia utente gli utenti non erano in grado di aggiungere articoli al carrello!)

Il client ricarica automaticamente le regole quando firestore.rules viene salvato. Quindi, prova ad aggiungere qualcosa al carrello.

Ricapitolare

Bel lavoro! Hai appena migliorato la sicurezza della tua app, un passaggio essenziale per prepararla alla produzione! Se si trattasse di un'app di produzione, potremmo aggiungere questi test alla nostra pipeline di integrazione continua. Questo ci darebbe fiducia in futuro che i dati del nostro carrello della spesa avranno questi controlli di accesso, anche se altri stanno modificando le regole.

Ma aspetta, c'è di più!

se continui imparerai:

• Come scrivere una funzione attivata da un evento Firestore
• Come creare test che funzionino su più emulatori

15. Configurare i test di Cloud Functions

Finora ci siamo concentrati sul frontend della nostra app Web e sulle regole di sicurezza di Firestore. Ma questa app utilizza anche Cloud Functions per mantenere aggiornato il carrello dell'utente, quindi vogliamo testare anche quel codice.

Emulator Suite rende così facile testare le funzioni cloud, anche le funzioni che utilizzano Cloud Firestore e altri servizi.

Nell'editor, apri il file emulators-codelab/codelab-initial-state/functions/test.js e scorri fino all'ultimo test nel file. In questo momento, è contrassegnato come in sospeso:

//  REMOVE .skip FROM THIS LINE
describe.skip("adding an item to the cart recalculates the cart total. ", () => {
  // ...

  it("should sum the cost of their items", async () => {
    ...
  });
});

Per abilitare il test, rimuovi .skip , in modo che assomigli a questo:

describe("adding an item to the cart recalculates the cart total. ", () => {
  // ...

  it("should sum the cost of their items", async () => {
    ...
  });
});

Successivamente, trova la variabile REAL_FIREBASE_PROJECT_ID nella parte superiore del file e modificala con il tuo vero ID progetto Firebase:

// CHANGE THIS LINE
const REAL_FIREBASE_PROJECT_ID = "changeme";

Se hai dimenticato l'ID progetto, puoi trovare l'ID progetto Firebase nelle Impostazioni progetto nella console Firebase:

16. Esaminate i test delle funzioni

Poiché questo test convalida l'interazione tra Cloud Firestore e Cloud Functions, richiede più configurazione rispetto ai test nei codelab precedenti. Esaminiamo questo test e facciamo un'idea di cosa si aspetta.

Nota : gli snippet di codice riportati di seguito hanno lo scopo di aiutarti a leggere e comprendere il codice già scritto. In questo passaggio, non devi assolutamente cambiare l'app!

Crea un carrello

Cloud Functions viene eseguito in un ambiente server attendibile e può utilizzare l'autenticazione dell'account di servizio utilizzata da Admin SDK . Innanzitutto, si inizializza un'app utilizzando initializeAdminApp invece di initializeApp . Quindi, crei un DocumentReference per il carrello a cui aggiungeremo gli articoli e inizializzeremo il carrello:

it("should sum the cost of their items", async () => {
    const db = firebase
        .initializeAdminApp({ projectId: REAL_FIREBASE_PROJECT_ID })
        .firestore();

    // Setup: Initialize cart
    const aliceCartRef = db.doc("carts/alice")
    await aliceCartRef.set({ ownerUID: "alice", totalPrice: 0 });

    ...
  });

Attiva la funzione

Quindi, aggiungi i documenti alla sottoraccolta items del nostro documento del carrello per attivare la funzione. Aggiungi due elementi per assicurarti di testare l'addizione che si verifica nella funzione.

it("should sum the cost of their items", async () => {
    const db = firebase
        .initializeAdminApp({ projectId: REAL_FIREBASE_PROJECT_ID })
        .firestore();

    // Setup: Initialize cart
    const aliceCartRef = db.doc("carts/alice")
    await aliceCartRef.set({ ownerUID: "alice", totalPrice: 0 });

    //  Trigger calculateCart by adding items to the cart
    const aliceItemsRef = aliceCartRef.collection("items");
    await aliceItemsRef.doc("doc1").set({name: "nectarine", price: 2.99});
    await aliceItemsRef.doc("doc2").set({ name: "grapefruit", price: 6.99 });

    ...
    });
  });

Imposta le aspettative del test

Utilizzare onSnapshot() per registrare un listener per eventuali modifiche al documento del carrello. onSnapshot() restituisce una funzione che puoi chiamare per annullare la registrazione del listener.

Perché ascoltare il documento del carrello piuttosto che un documento nella sottoraccolta degli articoli?

Sebbene la funzione sia attivata da operazioni di scrittura nella sottoraccolta items , la funzione aggiorna quindi il documento del carrello. Questo è un effetto collaterale della scrittura iniziale che vogliamo testare.

Per questo test, aggiungi due articoli che insieme costano $ 9,98. Quindi, controlla se il carrello contiene itemCount e totalPrice previsti. Se è così, allora la funzione ha fatto il suo lavoro.

it("should sum the cost of their items", (done) => {
    const db = firebase
        .initializeAdminApp({ projectId: REAL_FIREBASE_PROJECT_ID })
        .firestore();

    // Setup: Initialize cart
    const aliceCartRef = db.doc("carts/alice")
    aliceCartRef.set({ ownerUID: "alice", totalPrice: 0 });

    //  Trigger calculateCart by adding items to the cart
    const aliceItemsRef = aliceCartRef.collection("items");
    aliceItemsRef.doc("doc1").set({name: "nectarine", price: 2.99});
    aliceItemsRef.doc("doc2").set({ name: "grapefruit", price: 6.99 });
    
    // Listen for every update to the cart. Every time an item is added to
    // the cart's subcollection of items, the function updates `totalPrice`
    // and `itemCount` attributes on the cart.
    // Returns a function that can be called to unsubscribe the listener.
    await new Promise((resolve) => {
      const unsubscribe = aliceCartRef.onSnapshot(snap => {
        // If the function worked, these will be cart's final attributes.
        const expectedCount = 2;
        const expectedTotal = 9.98;
  
        // When the `itemCount`and `totalPrice` match the expectations for the
        // two items added, the promise resolves, and the test passes.
        if (snap.data().itemCount === expectedCount && snap.data().totalPrice == expectedTotal) {
          // Call the function returned by `onSnapshot` to unsubscribe from updates
          unsubscribe();
          resolve();
        };
      });
    });
   });
 });

17. Eseguire i test

Potresti avere ancora gli emulatori in esecuzione dai test precedenti. In caso contrario, avvia gli emulatori. Dalla riga di comando, esegui

$ firebase emulators:start --import=./seed

Apri una nuova scheda del terminale (lascia gli emulatori in esecuzione) e spostati nella directory delle funzioni. Potresti averlo ancora aperto dai test delle regole di sicurezza.

$ cd functions

Ora esegui i test unitari, dovresti vedere 5 test totali:

$ npm test

> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha

  shopping cart creation
    ✓ can be created by the cart owner (82ms)

  shopping cart reads, updates, and deletes
    ✓ cart can be read by the cart owner (42ms)

  shopping cart items
    ✓ items can be read by the cart owner (40ms)
    ✓ items can be added by the cart owner

  adding an item to the cart recalculates the cart total. 
    1) should sum the cost of their items

  4 passing (2s)
  1 failing

Se osservi l'errore specifico, sembra essere un errore di timeout. Questo perché il test è in attesa che la funzione si aggiorni correttamente, ma non lo fa mai. Ora siamo pronti a scrivere la funzione per soddisfare il test.

18. Scrivere una funzione

Per correggere questo test, è necessario aggiornare la funzione in functions/index.js . Sebbene parte di questa funzione sia scritta, non è completa. Ecco come appare attualmente la funzione:

// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
    .firestore.document("carts/{cartId}/items/{itemId}")
    .onWrite(async (change, context) => {
      console.log(`onWrite: ${change.after.ref.path}`);
      if (!change.after.exists) {
        // Ignore deletes
        return;
      }

      let totalPrice = 125.98;
      let itemCount = 8;
      try {
        
        const cartRef = db.collection("carts").doc(context.params.cartId);

        await cartRef.update({
          totalPrice,
          itemCount
        });
      } catch(err) {
      }
    });

La funzione imposta correttamente il riferimento al carrello, ma invece di calcolare i valori di totalPrice e itemCount , li aggiorna a quelli hardcoded.

Recupera e itera attraverso il file

sottoraccolta items

Inizializza una nuova costante, itemsSnap , come raccolta secondaria items . Quindi, scorrere tutti i documenti nella raccolta.

// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
    .firestore.document("carts/{cartId}/items/{itemId}")
    .onWrite(async (change, context) => {
      console.log(`onWrite: ${change.after.ref.path}`);
      if (!change.after.exists) {
        // Ignore deletes
        return;
      }


      try {
        let totalPrice = 125.98;
        let itemCount = 8;

        const cartRef = db.collection("carts").doc(context.params.cartId);
        // ADD LINES FROM HERE
        const itemsSnap = await cartRef.collection("items").get();

        itemsSnap.docs.forEach(item => {
          const itemData = item.data();
        })
        // TO HERE
       
        return cartRef.update({
          totalPrice,
          itemCount
        });
      } catch(err) {
      }
    });

Calcola totalPrice e itemCount

Per prima cosa, inizializziamo i valori di totalPrice e itemCount su zero.

Quindi, aggiungi la logica al nostro blocco di iterazione. Innanzitutto, controlla che l'articolo abbia un prezzo. Se per l'articolo non è stata specificata una quantità, impostala come valore predefinito su 1 . Quindi, aggiungi la quantità al totale parziale di itemCount . Infine, aggiungi il prezzo dell'articolo moltiplicato per la quantità al totale parziale di totalPrice :

// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
    .firestore.document("carts/{cartId}/items/{itemId}")
    .onWrite(async (change, context) => {
      console.log(`onWrite: ${change.after.ref.path}`);
      if (!change.after.exists) {
        // Ignore deletes
        return;
      }

      try {
        // CHANGE THESE LINES
        let totalPrice = 0;
        let itemCount = 0;

        const cartRef = db.collection("carts").doc(context.params.cartId);
        const itemsSnap = await cartRef.collection("items").get();

        itemsSnap.docs.forEach(item => {
          const itemData = item.data();
          // ADD LINES FROM HERE
          if (itemData.price) {
            // If not specified, the quantity is 1
            const quantity = itemData.quantity ? itemData.quantity : 1;
            itemCount += quantity;
            totalPrice += (itemData.price * quantity);
          }
          // TO HERE
        })

        await cartRef.update({
          totalPrice,
          itemCount
        });
      } catch(err) {
      }
    });

Puoi anche aggiungere la registrazione per aiutare a eseguire il debug degli stati di successo e di errore:

// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
    .firestore.document("carts/{cartId}/items/{itemId}")
    .onWrite(async (change, context) => {
      console.log(`onWrite: ${change.after.ref.path}`);
      if (!change.after.exists) {
        // Ignore deletes
        return;
      }

      let totalPrice = 0;
      let itemCount = 0;
      try {
        const cartRef = db.collection("carts").doc(context.params.cartId);
        const itemsSnap = await cartRef.collection("items").get();

        itemsSnap.docs.forEach(item => {
          const itemData = item.data();
          if (itemData.price) {
            // If not specified, the quantity is 1
            const quantity = (itemData.quantity) ? itemData.quantity : 1;
            itemCount += quantity;
            totalPrice += (itemData.price * quantity);
          }
        });

        await cartRef.update({
          totalPrice,
          itemCount
        });

        // OPTIONAL LOGGING HERE
        console.log("Cart total successfully recalculated: ", totalPrice);
      } catch(err) {
        // OPTIONAL LOGGING HERE
        console.warn("update error", err);
      }
    });

19. Eseguire nuovamente i test

Sulla riga di comando, assicurati che gli emulatori siano ancora in esecuzione ed esegui nuovamente i test. Non è necessario riavviare gli emulatori perché rilevano automaticamente le modifiche alle funzioni. Dovresti vedere tutti i test superati:

$ npm test
> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha

  shopping cart creation
    ✓ can be created by the cart owner (306ms)

  shopping cart reads, updates, and deletes
    ✓ cart can be read by the cart owner (59ms)

  shopping cart items
    ✓ items can be read by the cart owner
    ✓ items can be added by the cart owner

  adding an item to the cart recalculates the cart total. 
    ✓ should sum the cost of their items (800ms)


  5 passing (1s)

Buon lavoro!

20. Provalo utilizzando l'interfaccia utente di Storefront

Per il test finale, torna all'app web ( http://127.0.0.1:5000/ ) e aggiungi un articolo al carrello.

Conferma che il carrello si aggiorni con il totale corretto. Fantastico!

Ricapitolare

Hai esaminato un complesso test case tra Cloud Functions for Firebase e Cloud Firestore. Hai scritto una funzione cloud per superare il test. Hai anche confermato che la nuova funzionalità funziona nell'interfaccia utente! Hai fatto tutto questo localmente, eseguendo gli emulatori sulla tua macchina.

Hai anche creato un client Web in esecuzione sugli emulatori locali, regole di sicurezza personalizzate per proteggere i dati e testato le regole di sicurezza utilizzando gli emulatori locali.