Programowanie lokalne za pomocą pakietu emulatorów Firebase

1. Zanim zaczniesz

Bezserwerowe narzędzia zaplecza, takie jak Cloud Firestore i Cloud Functions, są bardzo łatwe w użyciu, ale mogą być trudne do przetestowania. Pakiet Firebase Local Emulator Suite umożliwia uruchamianie lokalnych wersji tych usług na komputerze programistycznym, dzięki czemu można szybko i bezpiecznie tworzyć aplikacje.

Wymagania wstępne

• Prosty edytor, taki jak Visual Studio Code, Atom lub Sublime Text
• Node.js 10.0.0 lub nowszy (aby zainstalować Node.js, użyj nvm , aby sprawdzić swoją wersję, uruchom node --version )
• Java 7 lub nowsza (aby zainstalować Javę, skorzystaj z tych instrukcji , aby sprawdzić swoją wersję, uruchom java -version )

Co zrobisz

W tym laboratorium kodowania uruchomisz i debugujesz prostą aplikację do zakupów online, która jest obsługiwana przez wiele usług Firebase:

• Cloud Firestore: globalnie skalowalna, bezserwerowa baza danych NoSQL z funkcjami czasu rzeczywistego.
• Cloud Functions : bezserwerowy kod zaplecza, który jest uruchamiany w odpowiedzi na zdarzenia lub żądania HTTP.
• Uwierzytelnianie Firebase : zarządzana usługa uwierzytelniania, która integruje się z innymi produktami Firebase.
• Hosting Firebase : szybki i bezpieczny hosting aplikacji internetowych.

Połączysz aplikację z pakietem Emulator Suite, aby umożliwić rozwój lokalny.

Dowiesz się również, jak:

• Jak połączyć swoją aplikację z pakietem Emulator Suite i jak połączone są różne emulatory.
• Jak działają reguły bezpieczeństwa Firebase i jak przetestować reguły bezpieczeństwa Firestore na lokalnym emulatorze.
• Jak napisać funkcję Firebase, która jest wyzwalana przez zdarzenia Firestore i jak napisać testy integracyjne, które działają na pakiecie emulatorów.

2. Skonfiguruj

Pobierz kod źródłowy

W tym laboratorium kodowania zaczynasz od wersji próbnej The Fire Store, która jest prawie ukończona, więc pierwszą rzeczą, którą musisz zrobić, to sklonować kod źródłowy:

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

Następnie przejdź do katalogu codelab, gdzie będziesz pracować przez pozostałą część tego codelab:

$ cd emulators-codelab/codelab-initial-state

Teraz zainstaluj zależności, aby móc uruchomić kod. Jeśli korzystasz z wolniejszego połączenia internetowego, może to potrwać minutę lub dwie:

# Move into the functions directory
$ cd functions

# Install dependencies
$ npm install

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

Pobierz interfejs wiersza polecenia Firebase

Pakiet emulatorów jest częścią Firebase CLI (interfejsu wiersza poleceń), który można zainstalować na komputerze za pomocą następującego polecenia:

$ npm install -g firebase-tools

Następnie potwierdź, że masz najnowszą wersję interfejsu CLI. To laboratorium kodów powinno działać z wersją 9.0.0 lub nowszą, ale nowsze wersje zawierają więcej poprawek błędów.

$ firebase --version
9.6.0

Połącz się ze swoim projektem Firebase

Jeśli nie masz projektu Firebase, w konsoli Firebase utwórz nowy projekt Firebase. Zanotuj wybrany identyfikator projektu, będzie potrzebny później.

Teraz musimy połączyć ten kod z twoim projektem Firebase. Najpierw uruchom następujące polecenie, aby zalogować się do Firebase CLI:

$ firebase login

Następnie uruchom następujące polecenie, aby utworzyć alias projektu. Zastąp $YOUR_PROJECT_ID identyfikatorem swojego projektu Firebase.

$ firebase use $YOUR_PROJECT_ID

Teraz możesz uruchomić aplikację!

3. Uruchom emulatory

W tej sekcji uruchomisz aplikację lokalnie. Oznacza to, że nadszedł czas, aby uruchomić pakiet emulatorów.

Uruchom emulatory

W katalogu źródłowym codelab uruchom następujące polecenie, aby uruchomić emulatory:

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

Powinieneś zobaczyć takie dane wyjściowe:

$ 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.

Gdy zobaczysz komunikat Wszystkie emulatory uruchomione , aplikacja jest gotowa do użycia.

Połącz aplikację internetową z emulatorami

Na podstawie tabeli w logach widzimy, że emulator Cloud Firestore nasłuchuje na porcie 8080 , a emulator Authentication nasłuchuje na porcie 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                             │
└────────────────┴────────────────┴─────────────────────────────────┘

Połączmy Twój kod frontendowy z emulatorem, a nie z produkcją. Otwórz plik public/js/homepage.js i znajdź funkcję onDocumentReady . Widzimy, że kod uzyskuje dostęp do standardowych instancji Firestore i Auth:

public/js/strona główna.js

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

Zaktualizujmy obiekty db i auth , aby wskazywały na lokalne emulatory:

public/js/strona główna.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);
  }

Teraz, gdy aplikacja działa na twoim komputerze lokalnym (obsługiwanym przez emulator Hostingu), klient Firestore również wskazuje na lokalny emulator, a nie na produkcyjną bazę danych.

Otwórz interfejs użytkownika emulatora

W przeglądarce internetowej przejdź do http://127.0.0.1:4000/ . Powinieneś zobaczyć interfejs Emulator Suite.

Kliknij, aby zobaczyć interfejs użytkownika emulatora Firestore. Kolekcja items zawiera już dane ze względu na dane zaimportowane z flagą --import .

4. Uruchom aplikację

Otwórz aplikację

W przeglądarce przejdź do http://127.0.0.1:5000 i powinieneś zobaczyć, że Fire Store działa lokalnie na twoim komputerze!

Skorzystaj z aplikacji

Wybierz przedmiot na stronie głównej i kliknij Dodaj do koszyka . Niestety napotkasz następujący błąd:

Naprawmy ten błąd! Ponieważ wszystko działa w emulatorach, możemy eksperymentować i nie martwić się o wpływ na rzeczywiste dane.

5. Debuguj aplikację

Znajdź błąd

Ok, spójrzmy w konsolę programisty Chrome. Naciśnij klawisze Control+Shift+J (Windows, Linux, Chrome OS) lub Command+Option+J (Mac), aby wyświetlić błąd na konsoli:

Wygląda na to, że wystąpił błąd w metodzie addToCart , przyjrzyjmy się temu. Gdzie próbujemy uzyskać dostęp do czegoś, co nazywa się uid w tej metodzie i dlaczego miałoby być null ? W tej chwili metoda wygląda tak w public/js/homepage.js :

public/js/strona główna.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);
  }

Aha! Nie jesteśmy zalogowani do aplikacji. Zgodnie z dokumentacją Firebase Authentication , gdy nie jesteśmy zalogowani, auth.currentUser ma null . Dodajmy do tego czek:

public/js/strona główna.js

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

    // ...
  }

Przetestuj aplikację

Teraz odśwież stronę, a następnie kliknij Dodaj do koszyka . Tym razem powinieneś dostać ładniejszy błąd:

Jeśli jednak klikniesz Zaloguj się na górnym pasku narzędzi, a następnie ponownie klikniesz Dodaj do koszyka , zobaczysz, że koszyk został zaktualizowany.

Jednak wygląda na to, że liczby wcale nie są poprawne:

Nie martw się, wkrótce naprawimy ten błąd. Najpierw przyjrzyjmy się dokładnie temu, co się właściwie stało, kiedy dodałeś przedmiot do koszyka.

6. Wyzwalacze funkcji lokalnych

Kliknięcie Dodaj do koszyka rozpoczyna łańcuch zdarzeń obejmujących wiele emulatorów. Po dodaniu produktu do koszyka w dziennikach interfejsu Firebase CLI powinny pojawić się następujące komunikaty:

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

Wystąpiły cztery kluczowe zdarzenia, które spowodowały utworzenie tych dzienników i zaobserwowanej aktualizacji interfejsu użytkownika:

1) Zapis Firestore — Klient

Do kolekcji Firestore zostanie dodany nowy dokument /carts/{cartId}/items/{itemId}/ . Możesz zobaczyć ten kod w funkcji addToCart wewnątrz public/js/homepage.js :

public/js/strona główna.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) Uruchomiono funkcję chmury

Funkcja cloud calculateCart nasłuchuje wszelkich zdarzeń zapisu (tworzenia, aktualizacji lub usuwania), które mają miejsce w przypadku elementów koszyka, używając wyzwalacza onWrite , który można zobaczyć w functions/index.js :

funkcje/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) Zapis Firestore — administrator

Funkcja calculateCart odczytuje wszystkie pozycje w koszyku i sumuje całkowitą ilość oraz cenę, a następnie aktualizuje dokument „koszyk” o nowe sumy (patrz cartRef.update(...) powyżej).

4) Firestore Odczyt - Klient

Frontend internetowy jest zasubskrybowany do otrzymywania aktualizacji o zmianach w koszyku. Otrzymuje aktualizację w czasie rzeczywistym po tym, jak funkcja chmury zapisze nowe sumy i zaktualizuje interfejs użytkownika, jak widać w public/js/homepage.js :

public/js/strona główna.js

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

Podsumowanie

Dobra robota! Właśnie skonfigurowałeś w pełni lokalną aplikację, która używa trzech różnych emulatorów Firebase do w pełni lokalnych testów.

Ale poczekaj, jest więcej! W następnej sekcji dowiesz się:

• Jak pisać testy jednostkowe korzystające z emulatorów Firebase.
• Jak używać emulatorów Firebase do debugowania reguł bezpieczeństwa.

7. Stwórz reguły bezpieczeństwa dostosowane do Twojej aplikacji

Nasza aplikacja internetowa odczytuje i zapisuje dane, ale jak dotąd w ogóle nie martwiliśmy się o bezpieczeństwo. Cloud Firestore używa systemu o nazwie „Zasady bezpieczeństwa”, aby zadeklarować, kto ma dostęp do odczytu i zapisu danych. Emulator Suite to świetny sposób na prototypowanie tych reguł.

W edytorze otwórz plik emulators-codelab/codelab-initial-state/firestore.rules . Zobaczysz, że w naszych zasadach mamy trzy główne sekcje:

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;
    }
  }
}

W tej chwili każdy może odczytywać i zapisywać dane w naszej bazie danych! Chcemy mieć pewność, że przejdą tylko ważne operacje i że nie dojdzie do wycieku żadnych poufnych informacji.

Podczas tego laboratorium kodowania, zgodnie z zasadą najmniejszych uprawnień, zablokujemy wszystkie dokumenty i stopniowo dodamy dostęp, aż wszyscy użytkownicy uzyskają pełny dostęp, którego potrzebują, ale nie więcej. Zaktualizujmy pierwsze dwie reguły, aby odmówić dostępu, ustawiając warunek na 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;
    }
  }
}

8. Uruchom emulatory i testy

Uruchom emulatory

W wierszu polecenia upewnij się, że jesteś w trybie emulators-codelab/codelab-initial-state/ . Być może nadal masz uruchomione emulatory z poprzednich kroków. Jeśli nie, uruchom ponownie emulatory:

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

Po uruchomieniu emulatorów można lokalnie przeprowadzać na nich testy.

Uruchom testy

W wierszu poleceń w nowej karcie terminala z katalogu emulators-codelab/codelab-initial-state/

Najpierw przejdź do katalogu funkcji (zostaniemy tutaj do końca laboratorium):

$ cd functions

Teraz uruchom testy mocha w katalogu funkcji i przewiń do góry danych wyjściowych:

# 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

Na razie mamy cztery porażki. Tworząc plik reguł, możesz mierzyć postępy, obserwując, jak przechodzi kolejne testy.

9. Bezpieczny dostęp do wózka

Pierwsze dwie awarie to testy „koszyka na zakupy”, które sprawdzają, czy:

• Użytkownicy mogą tworzyć i aktualizować tylko własne koszyki
• Użytkownicy mogą czytać tylko własne koszyki

funkcje/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());
  });

Sprawmy, by te testy przeszły pomyślnie. W edytorze otwórz plik reguł bezpieczeństwa, firestore.rules i zaktualizuj instrukcje w match /carts/{cartID} :

sklep.reguły

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;
    }

    // ...
  }
}

Te reguły zezwalają teraz tylko na dostęp do odczytu i zapisu dla właściciela koszyka.

Do weryfikacji przychodzących danych i uwierzytelnienia użytkownika używamy dwóch obiektów, które są dostępne w kontekście każdej reguły:

• Obiekt request zawiera dane i metadane dotyczące wykonywanej operacji.
• Jeśli projekt Firebase korzysta z uwierzytelniania Firebase , obiekt request.auth opisuje użytkownika, który wysyła żądanie.

10. Dostęp do wózka testowego

Emulator Suite automatycznie aktualizuje reguły za każdym razem, gdy zostanie zapisany firestore.rules . Możesz potwierdzić, że emulator zaktualizował reguły, sprawdzając w zakładce z emulatorem komunikat Rules updated :

Uruchom ponownie testy i sprawdź, czy pierwsze dwa testy zakończyły się pomyślnie:

$ 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

Dobra robota! Masz teraz zabezpieczony dostęp do koszyków. Przejdźmy do następnego nieudanego testu.

11. Sprawdź przepływ „Dodaj do koszyka” w interfejsie użytkownika

W tej chwili, chociaż właściciele koszyków mogą czytać i zapisywać w koszyku, nie mogą czytać ani zapisywać poszczególnych pozycji w koszyku. Dzieje się tak, ponieważ chociaż właściciele mają dostęp do dokumentu koszyka, nie mają dostępu do podkolekcji elementów koszyka .

To jest zepsuty stan dla użytkowników.

Wróć do internetowego interfejsu użytkownika działającego pod adresem http://127.0.0.1:5000, i spróbuj dodać coś do koszyka. Pojawia się błąd Permission Denied , widoczny w konsoli debugowania, ponieważ nie przyznaliśmy jeszcze użytkownikom dostępu do utworzonych dokumentów w podkolekcji items .

12. Zezwól na dostęp do elementów koszyka

Te dwa testy potwierdzają, że użytkownicy mogą dodawać lub czytać produkty tylko z własnego koszyka:

  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
    }));
  });

Możemy więc napisać regułę, która zezwala na dostęp, jeśli bieżący użytkownik ma taki sam identyfikator UID, jak identyfikator właściciela w dokumencie koszyka. Ponieważ nie ma potrzeby określania różnych reguł create, update, delete , można użyć reguły write , która ma zastosowanie do wszystkich żądań modyfikujących dane.

Zaktualizuj regułę dla dokumentów w podkolekcji elementów. get warunkowe polega na odczytaniu wartości z Firestore — w tym przypadku ownerUID w dokumencie koszyka.

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;
    }

    // ...
  }
}

13. Testuj dostęp do elementów koszyka

Teraz możemy powtórzyć test. Przewiń do góry danych wyjściowych i sprawdź, czy przeszło więcej testów:

$ 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

Ładny! Teraz wszystkie nasze testy przechodzą pomyślnie. Mamy jeden oczekujący test, ale przejdziemy do niego w kilku krokach.

14. Sprawdź ponownie przepływ „dodaj do koszyka”.

Wróć do interfejsu internetowego ( http://127.0.0.1:5000 ) i dodaj element do koszyka. Jest to ważny krok w celu potwierdzenia, że ​​nasze testy i reguły pasują do funkcjonalności wymaganej przez klienta. (Pamiętaj, że ostatnim razem, gdy wypróbowaliśmy interfejs użytkownika, użytkownicy nie mogli dodawać produktów do koszyka!)

Klient automatycznie ładuje ponownie reguły po zapisaniu pliku firestore.rules . Spróbuj więc dodać coś do koszyka.

Podsumowanie

Dobra robota! Właśnie poprawiłeś bezpieczeństwo swojej aplikacji, co jest niezbędnym krokiem w przygotowaniu jej do produkcji! Gdyby to była aplikacja produkcyjna, moglibyśmy dodać te testy do naszego potoku ciągłej integracji. Dałoby nam to pewność, że w przyszłości dane naszego koszyka będą miały kontrolę dostępu, nawet jeśli inni modyfikują zasady.

Ale poczekaj, jest więcej!

jeśli będziesz kontynuować, dowiesz się:

• Jak napisać funkcję wyzwalaną przez zdarzenie Firestore
• Jak tworzyć testy, które działają na wielu emulatorach

15. Skonfiguruj testy Cloud Functions

Do tej pory skupialiśmy się na interfejsie naszej aplikacji internetowej i zasadach bezpieczeństwa Firestore. Ale ta aplikacja korzysta również z funkcji Cloud Functions, aby aktualizować koszyk użytkownika, dlatego też chcemy przetestować ten kod.

Emulator Suite sprawia, że ​​testowanie funkcji Cloud Functions jest bardzo łatwe, nawet tych, które korzystają z Cloud Firestore i innych usług.

W edytorze otwórz plik emulators-codelab/codelab-initial-state/functions/test.js i przewiń do ostatniego testu w pliku. W tej chwili jest oznaczony jako oczekujący:

//  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 () => {
    ...
  });
});

Aby włączyć test, usuń .skip , aby wyglądało to tak:

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

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

Następnie znajdź zmienną REAL_FIREBASE_PROJECT_ID na górze pliku i zmień ją na swój prawdziwy identyfikator projektu Firebase:

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

Jeśli nie pamiętasz identyfikatora projektu, możesz znaleźć identyfikator projektu Firebase w ustawieniach projektu w konsoli Firebase:

16. Przejdź przez testy funkcji

Ponieważ ten test weryfikuje interakcję między Cloud Firestore i Cloud Functions, wymaga więcej konfiguracji niż testy w poprzednich laboratoriach kodu. Przejdźmy przez ten test i dowiedzmy się, czego oczekuje.

Utwórz koszyk

Cloud Functions działają w środowisku zaufanego serwera i mogą korzystać z uwierzytelniania konta usługi używanego przez pakiet Admin SDK . Najpierw inicjujesz aplikację za pomocą initializeAdminApp zamiast initializeApp . Następnie tworzysz DocumentReference dla koszyka, do którego będziemy dodawać elementy i inicjalizuj koszyk:

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 });

    ...
  });

Uruchom funkcję

Następnie dodaj dokumenty do podkolekcji items naszego dokumentu koszyka w celu uruchomienia funkcji. Dodaj dwa elementy, aby upewnić się, że testujesz dodatek, który ma miejsce w funkcji.

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 });

    ...
    });
  });

Ustaw oczekiwania testowe

Użyj funkcji onSnapshot() do zarejestrowania odbiornika dla wszelkich zmian w dokumencie koszyka. onSnapshot() zwraca funkcję, którą możesz wywołać, aby wyrejestrować słuchacza.

Do tego testu dodaj dwa przedmioty, które razem kosztują 9,98 USD. Następnie sprawdź, czy koszyk zawiera oczekiwane itemCount i totalPrice . Jeśli tak, to funkcja spełniła swoje zadanie.

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. Uruchom testy

Być może nadal masz uruchomione emulatory z poprzednich testów. Jeśli nie, uruchom emulatory. Z wiersza poleceń uruchom

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

Otwórz nową kartę terminala (pozostaw emulatory uruchomione) i przejdź do katalogu funkcji. Możesz nadal mieć to otwarte z testów reguł bezpieczeństwa.

$ cd functions

Teraz uruchom testy jednostkowe, powinieneś zobaczyć łącznie 5 testów:

$ 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

Jeśli spojrzysz na konkretną awarię, wydaje się, że jest to błąd przekroczenia limitu czasu. Dzieje się tak, ponieważ test czeka na poprawną aktualizację funkcji, ale nigdy tego nie robi. Teraz jesteśmy gotowi do napisania funkcji spełniającej test.

18. Napisz funkcję

Aby naprawić ten test, musisz zaktualizować funkcję w functions/index.js . Chociaż część tej funkcji jest napisana, nie jest kompletna. Tak wygląda obecnie funkcja:

// 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) {
      }
    });

Funkcja poprawnie ustawia odniesienie do koszyka, ale zamiast obliczać wartości totalPrice i itemCount , aktualizuje je do zakodowanych na stałe.

Pobieranie i iteracja przez

podkolekcja items

Zainicjuj nową stałą, itemsSnap , aby była podkolekcją items . Następnie przejrzyj wszystkie dokumenty w kolekcji.

// 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) {
      }
    });

Oblicz totalPrice i itemCount

Najpierw zainicjujmy wartości totalPrice i itemCount na zero.

Następnie dodaj logikę do naszego bloku iteracyjnego. Najpierw sprawdź, czy przedmiot ma cenę. Jeśli pozycja nie ma określonej ilości, niech domyślna jest 1 . Następnie dodaj ilość do sumy bieżącej elementu itemCount . Na koniec dodaj cenę przedmiotu pomnożoną przez ilość do sumy bieżącej 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) {
      }
    });

Możesz także dodać rejestrowanie, aby ułatwić debugowanie stanów pomyślnych i błędów:

// 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. Ponownie wykonaj testy

W wierszu poleceń upewnij się, że emulatory nadal działają, i ponownie uruchom testy. Nie trzeba ponownie uruchamiać emulatorów, ponieważ automatycznie pobierają one zmiany w funkcjach. Powinieneś zobaczyć, że wszystkie testy przeszły pomyślnie:

$ 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)

Dobra robota!

20. Wypróbuj za pomocą interfejsu Storefront

Aby wykonać końcowy test, wróć do aplikacji internetowej ( http://127.0.0.1:5000/ ) i dodaj element do koszyka.

Potwierdź, że koszyk został zaktualizowany z prawidłową sumą. Fantastyczny!

Podsumowanie

Masz za sobą złożony przypadek testowy między Cloud Functions for Firebase i Cloud Firestore. Napisałeś funkcję Cloud Function, aby pomyślnie przejść test. Potwierdziliście również, że nowa funkcjonalność działa w interfejsie użytkownika! Robiłeś to wszystko lokalnie, uruchamiając emulatory na własnej maszynie.

Utworzono również klienta sieci Web, który działa z lokalnymi emulatorami, dostosowano reguły bezpieczeństwa w celu ochrony danych i przetestowano reguły bezpieczeństwa przy użyciu lokalnych emulatorów.