Ta strona została przetłumaczona przez Cloud Translation API.

Programowanie lokalne dzięki Pakietowi emulatorów Firebase

1. Zanim zaczniesz

Bezserwerowe narzędzia backendu, takie jak Cloud Firestore i Cloud Functions, są bardzo łatwe w użyciu, ale mogą być trudne do przetestowania. Pakiet emulatorów lokalnych Firebase umożliwia uruchamianie lokalnych wersji tych usług na komputerze, z którego korzystasz, dzięki czemu możesz szybko i bezpiecznie tworzyć aplikacje.

Wymagania wstępne

Prosty edytor, taki jak Visual Studio Code, Atom lub Sublime Text
Node.js w wersji 10.0.0 lub nowszej (aby zainstalować Node.js, użyj nvm, aby sprawdzić wersję, uruchom node --version)
Java 7 lub nowsza (aby zainstalować Javę, wykonaj te instrukcje, aby sprawdzić wersję, uruchom java -version)

Co trzeba zrobić

W ramach tego ćwiczenia w Codelabs dowiesz się, jak uruchomić i debugować prostą aplikację do zakupów online, która korzysta z wielu usług Firebase:

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

Aby umożliwić lokalne programowanie, połączysz aplikację z Pakietem emulatorów.

Dowiesz się również, jak:

Dowiedz się, jak połączyć aplikację z Pakietem emulatorów i w jaki sposób są one ze sobą połączone.
Jak działają reguły zabezpieczeń Firebase i jak przetestować reguły zabezpieczeń Firestore przy użyciu lokalnego emulatora.
Jak napisać funkcję Firebase aktywowaną przez zdarzenia Firestore oraz jak pisać testy integracji uruchamiane z użyciem Pakietu emulatorów.

2. Skonfiguruj

Pobieranie kodu źródłowego

W tym ćwiczeniu w programowaniu zaczniesz od przykładowej wersji The Fire Store, która jest prawie gotowa, więc najpierw musisz skopiować kod źródłowy:

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

Następnie przejdź do katalogu ćwiczeń z programowania, w którym będziesz pracować do końca tego ćwiczenia:

$ cd emulators-codelab/codelab-initial-state

Teraz zainstaluj zależności, aby uruchomić kod. Jeśli masz wolniejsze połączenie, może to potrwać kilka minut:

# Move into the functions directory
$ cd functions

# Install dependencies
$ npm install

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

Pobieranie interfejsu wiersza poleceń Firebase

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

$ npm install -g firebase-tools

Następnie sprawdź, czy masz najnowszą wersję interfejsu wiersza poleceń. To ćwiczenie w Codelabs powinno działać w wersji 9.0.0 lub nowszej, ale nowsze wersje zawierają więcej poprawek błędów.

$ firebase --version
9.6.0

Połącz z projektem Firebase

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

Teraz musimy połączyć ten kod z Twoim projektem Firebase. Najpierw uruchom to polecenie, aby zalogować się w interfejsie wiersza poleceń Firebase:

$ firebase login

Następnie uruchom poniższe polecenie, aby utworzyć alias projektu. Zastąp $YOUR_PROJECT_ID identyfikatorem projektu Firebase.

$ firebase use $YOUR_PROJECT_ID

Teraz możesz uruchomić aplikację.

3. Uruchamianie emulatorów

W tej sekcji uruchomisz aplikację lokalnie. Oznacza to, że pora uruchomić Pakiet emulatorów.

Uruchamianie emulatorów

W katalogu źródłowym ćwiczeń z programowania uruchom to polecenie, aby uruchomić emulatory:

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

Dane wyjściowe powinny wyglądać tak:

$ 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 pojawi się komunikat Wszystkie emulatory zostały uruchomione, aplikacja jest gotowa do użycia.

Łączenie aplikacji internetowej z emulatorami

Z tabeli w logach wynika, że emulator Cloud Firestore nasłuchuje na porcie 8080, a emulator uwierzytelniania 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 frontendu z emulatorem, a nie z profilem produkcyjnym. 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_glowna.js

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

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

public/js/strona_glowna.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);
  }

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

Otwórz EmulatorUI

W przeglądarce otwórz stronę http://127.0.0.1:4000/. Powinien wyświetlić się interfejs użytkownika Pakietu emulatorów.

Ekran główny interfejsu emulatorów

Kliknij, aby wyświetlić interfejs emulatora Firestore. Kolekcja items zawiera już dane ze względu na dane zaimportowane za pomocą flagi --import.

4. Uruchom aplikację

Otwórz aplikację

W przeglądarce otwórz stronę http://127.0.0.1:5000. Sklep Fire Store powinien działać lokalnie na Twoim komputerze.

W aplikacji

Wybierz produkt na stronie głównej i kliknij Dodaj do koszyka. Pojawi się następujący błąd:

Naprawmy ten błąd. Ponieważ wszystko działa w emulatorach, możemy eksperymentować bez obaw o wpływ na rzeczywiste dane.

5. Debuguj aplikację

Znajdź błąd

Przejdźmy do konsoli programisty Chrome. Naciśnij Control+Shift+J (Windows, Linux, Chrome OS) lub Command+Option+J (Mac), aby wyświetlić błąd w konsoli:

Wygląda na to, że w metodzie addToCart wystąpił błąd. Sprawdźmy to. Gdzie w tej metodzie próbujemy uzyskać dostęp do elementu o nazwie uid i dlaczego jest to null? Obecnie metoda wygląda tak w public/js/homepage.js:

public/js/strona_glowna.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 zalogowano się w aplikacji. Zgodnie z dokumentacją Uwierzytelniania Firebase, gdy nie jesteś zalogowany, auth.currentUser to null. Dodajmy weryfikację:

public/js/strona_glowna.js

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

    // ...
  }

Testowanie aplikacji

Odśwież stronę, a potem kliknij Dodaj do koszyka. Tym razem powinien wyświetlić się bardziej przejrzysty błąd:

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

Wydaje się jednak, że te liczby w ogóle nie są poprawne:

Bez obaw, wkrótce naprawimy ten błąd. Najpierw przyjrzyjmy się dokładniej, co tak naprawdę się stało, gdy użytkownik dodał produkt do koszyka.

6. Aktywatory funkcji lokalnych

Kliknięcie Dodaj do koszyka uruchamia łańcuch zdarzeń, które obejmują kilka emulatorów. Gdy dodasz produkt do koszyka, w logach interfejsu wiersza poleceń Firebase powinny pojawić się następujące komunikaty:

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

Podczas generowania tych logów i zaobserwowanej aktualizacji interfejsu użytkownika wystąpiły 4 kluczowe zdarzenia:

1) Zapis Firestore – klient

Nowy dokument zostanie dodany do kolekcji Firestore /carts/{cartId}/items/{itemId}/. Ten kod znajdziesz w funkcji addToCart w public/js/homepage.js:

public/js/strona_glowna.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) Aktywowano funkcję w Cloud Functions

Funkcja calculateCart w Cloud Functions nasłuchuje wszystkich zdarzeń zapisu (utworzenia, aktualizacji lub usuwania), które przydarzyły się elementom koszyka, przy użyciu aktywatora onWrite, który widać w tabeli functions/index.js:

functions/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 produkty w koszyku, sumuje ich łączną liczbę i cenę, a następnie aktualizuje „koszyk”. dokument z nowymi sumami (patrz cartRef.update(...) powyżej).

4) Odczyt Firestore – klient

Web frontend subskrybuje aktualizacje dotyczące zmian w koszyku. Otrzymuje aktualizację w czasie rzeczywistym, gdy funkcja w Cloud Functions zapisze nowe sumy i zaktualizuje interfejs użytkownika, jak widać w public/js/homepage.js:

public/js/strona_glowna.js

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

Podsumowanie

Dobra robota! Właśnie konfigurujesz aplikację w pełni lokalną, która korzysta z 3 różnych emulatorów Firebase do w pełni lokalnych testów.

Poczekaj, to jeszcze nie wszystko. Z następnej sekcji dowiesz się:

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

7. Tworzenie reguł zabezpieczeń dostosowanych do Twojej aplikacji

Nasza aplikacja internetowa odczytuje i zapisuje dane, ale w ogóle nie martwić się o bezpieczeństwo. Cloud Firestore używa systemu o nazwie „Reguły zabezpieczeń” deklarowania, kto może odczytywać i zapisywać dane. Pakiet emulatorów to doskonały sposób na opracowanie prototypu tych reguł.

W edytorze otwórz plik emulators-codelab/codelab-initial-state/firestore.rules. Reguły obejmują 3 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;
    }
  }
}

Obecnie każdy może odczytywać i zapisywać dane w naszej bazie danych. Chcemy mieć pewność, że dopuszczą się tylko prawidłowe operacje i nie wyciekniemy żadnych informacji poufnych.

Podczas tych ćwiczeń w programie zgodnie z zasadą najmniejszych uprawnień zablokujemy wszystkie dokumenty i stopniowo będziemy dodawać do nich dostęp aż do momentu, w którym wszyscy użytkownicy uzyskają potrzebne uprawnienia. Zaktualizujmy pierwsze 2 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. Uruchamianie emulatorów i testów

Uruchamianie emulatorów

W wierszu poleceń sprawdź, czy jesteś w trybie emulators-codelab/codelab-initial-state/. Emulatory mogą nadal być uruchomione w poprzednich krokach. Jeśli tak nie jest, ponownie uruchom emulatory:

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

Po uruchomieniu emulatorów możesz przeprowadzić na nich lokalne testy.

Przeprowadzanie testów

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

Najpierw przejdź do katalogu funkcji (zostaną tu do końca tego ćwiczenia):

$ cd functions

Teraz uruchom testy mokki w katalogu funkcji i przewiń do początku 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

Obecnie mamy 4 błędy. W miarę tworzenia pliku reguł możesz monitorować postępy, śledząc więcej zaliczonych testów.

9. Bezpieczny dostęp do koszyka

Pierwsze 2 błędy to „koszyk na zakupy”, który sprawdza, czy:

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

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

Postarajmy się, by te testy były zaliczone. W edytorze otwórz plik reguł zabezpieczeń firestore.rules i zaktualizuj instrukcje w 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;
    }

    // ...
  }
}

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

Aby zweryfikować przychodzące dane i uwierzytelnianie użytkownika, używamy 2 obiektów dostępnych 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 zgłasza żądanie.

10. Testowanie dostępu do koszyka

Pakiet emulatorów automatycznie aktualizuje reguły za każdym razem, gdy firestore.rules jest zapisywany. Aby sprawdzić, czy emulator zaktualizował reguły, sprawdź na karcie, w której działa emulator, pod kątem wiadomości Rules updated:

Ponownie uruchom testy i sprawdź, czy 2 pierwsze zostały zaliczone:

$ 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 koszyka na zakupy. Przejdźmy do kolejnego zakończonego niepowodzeniem testu.

11. Sprawdź opcję „Dodaj do koszyka”. przepływ w interfejsie

Obecnie, chociaż właściciele koszyków odczytują i zapisują elementy w koszyku, nie mogą w nim odczytywać ani zapisywać poszczególnych produktów. Dzieje się tak, ponieważ właściciele mają dostęp do dokumentu koszyka, ale nie mają dostępu do podkolekcji elementów koszyka.

To jest nieprawidłowy stan w przypadku użytkowników.

Wróć do interfejsu internetowego, który działa na urządzeniu 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 kolekcji podrzędnej items.

12. Zezwalaj na dostęp do elementów koszyka

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

  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łę zezwalającą na dostęp, jeśli bieżący użytkownik ma ten sam identyfikator UID co identyfikator właścicielaUID w dokumencie koszyka. W przypadku parametru create, update, delete nie trzeba określać różnych reguł, dlatego możesz 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 w warunkowym odczytuje wartość 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. Testowanie dostępu do elementów koszyka

Możemy teraz ponownie przeprowadzić test. Przewiń do góry danych wyjściowych i sprawdź, czy więcej testów zalicza się do zaliczenia:

$ 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

Świetnie! Teraz wszystkie testy zaliczone. Mamy jeden oczekujący test, ale zrobimy to za pomocą kilku kroków.

14. Zaznacz opcję „Dodaj do koszyka”. przepływ ponownie

Wróć do interfejsu internetowego ( http://127.0.0.1:5000) i dodaj produkt do koszyka. Jest to ważny krok, który pozwoli nam upewnić się, że nasze testy i reguły pasują do funkcji wymaganych przez klienta. (Pamiętaj, że podczas ostatniego testowania interfejsu użytkownicy nie mogli dodawać produktów do koszyka).

Klient automatycznie odświeża reguły po zapisaniu reguły firestore.rules. Spróbuj więc dodać coś do koszyka.

Podsumowanie

Dobra robota! Udało Ci się zwiększyć bezpieczeństwo aplikacji – to kluczowy etap przygotowań do wdrożenia wersji produkcyjnej. Gdyby była to aplikacja produkcyjna, moglibyśmy dodać takie testy do naszego potoku ciągłej integracji. Dzięki temu będziemy mieć pewność, że w przyszłości dane koszyka na zakupy będą podlegać kontroli dostępu, nawet jeśli inni będą modyfikować reguły.

To nie wszystko.

Jeśli przejdziesz dalej, dowiesz się:

Jak napisać funkcję uruchamianą przez zdarzenie Firestore
Jak tworzyć testy działające z użyciem wielu emulatorów

15. Konfigurowanie testów w Cloud Functions

Na razie skupialiśmy się na frontendzie naszej aplikacji internetowej i regułach zabezpieczeń Firestore. Aplikacja wykorzystuje jednak Cloud Functions do aktualizowania koszyka użytkownika, więc chcemy przetestować także ten kod.

Pakiet emulatorów ułatwia testowanie Cloud Functions, nawet funkcji korzystających 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. Obecnie jest oznaczone jako oczekujące:

//  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ń fragment .skip. Wygląda 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 u góry pliku i zmień ją na rzeczywisty identyfikator projektu Firebase:

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

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

16. Zapoznaj się z testami funkcji

Ten test weryfikuje interakcję między Cloud Firestore a Cloud Functions, dlatego wymaga więcej konfiguracji niż testy z poprzednich ćwiczeń z programowania. Przyjrzyjmy się teraz testowi i zobaczmy, czego można się spodziewać.

Tworzenie koszyka

Funkcje w Cloud Functions działają w zaufanym środowisku serwera i mogą korzystać z uwierzytelniania konta usługi używanego przez pakiet Admin SDK . Najpierw inicjujesz aplikację przy użyciu polecenia initializeAdminApp zamiast initializeApp. Następnie utwórz dokument DocumentReference dla koszyka, który dodamy do koszyka i do niego zainicjujemy:

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

    ...
  });

Aktywowanie funkcji

Następnie dodaj dokumenty do podkolekcji items dokumentu koszyka, aby aktywować tę funkcję. Dodaj 2 elementy, aby upewnić się, że testujesz dodawanie, które dzieje się 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 });

    ...
    });
  });

Ustal oczekiwania dotyczące testu

Użyj onSnapshot(), aby zarejestrować detektor zmian w dokumencie koszyka. onSnapshot() zwraca funkcję, którą możesz wywołać, aby wyrejestrować odbiornik.

W przypadku tego testu dodaj 2 produkty, które łącznie kosztują 9,98 PLN. Następnie sprawdź, czy w koszyku znajdują się oczekiwane atrybuty itemCount i totalPrice. Jeśli tak, 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. Przeprowadzanie testów

Możesz mieć nadal uruchomione emulatory z poprzednich testów. Jeśli tak nie jest, uruchom emulatory. W wierszu poleceń uruchom:

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

Otwórz nową kartę terminala (pozostaw emulatory uruchomione) i przejdź do katalogu funkcji. Ten element może być nadal otwarty w testach reguł zabezpieczeń.

$ cd functions

Gdy uruchomisz testy jednostkowe, powinno się wyświetlić łą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 konkretny błąd, wygląda na to, że upłynął limit czasu. Dzieje się tak, ponieważ test czeka na poprawną aktualizację funkcji, ale nigdy się nie dzieje. Teraz możemy napisać funkcję spełniającą wymagania testu.

18. Napisz funkcję

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

// 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 prawidłowo ustawia odwołanie do koszyka, ale zamiast obliczać wartości totalPrice i itemCount, aktualizuje je do wartości zakodowanych na stałe.

Pobieranie i powtarzanie

items kolekcja podrzędna

Zainicjuj nową stałą (itemsSnap), która będzie podkolekcją items. Następnie powtórz 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) {
      }
    });

Obliczanie wartości totalPrice i itemCount

Najpierw zainicjujmy wartości totalPrice i itemCount do zera.

Następnie dodaj tę logikę do naszego bloku iteracji. Najpierw sprawdź, czy produkt ma cenę. Jeśli w przypadku produktu nie określono ilości, użyj domyślnej wartości 1. Następnie dodaj ilość do bieżącej sumy wynoszącej itemCount. Na koniec dodaj cenę produktu pomnożoną przez liczbę do bieżącej sumy (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 też dodać logowanie, aby ułatwić debugowanie stanów powodzenia i błędu:

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

W wierszu poleceń sprawdź, czy emulatory są nadal uruchomione, i ponownie uruchom testy. Nie musisz ponownie uruchamiać emulatorów, ponieważ automatycznie wykrywają one zmiany w funkcjach. Powinny się wyświetlić wszystkie testy zaliczone:

$ 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 witryny sklepowej

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

Sprawdź, czy wartość w koszyku została zaktualizowana. Świetnie.

Podsumowanie

Udało Ci się przeprowadzić złożony przypadek testowy między Cloud Functions dla Firebase a Cloud Firestore. Masz już utworzoną funkcję w Cloud Functions, która zalicza testy. Potwierdzasz również, że nowa funkcja działa w interfejsie. Wszystko to zrobisz lokalnie, uruchamiając emulatory na własnym komputerze.

Masz już klienta internetowego, który działa w oparciu o lokalne emulatory, masz przygotowane reguły zabezpieczeń chroniące dane, a także przetestowałeś(-aś) reguły przy użyciu lokalnych emulatorów.