1. Zanim zaczniesz
Narzędzia backendu bezserwerowego, 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 używanym do programowania, 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ę, postępuj zgodnie z tymi instrukcjami; aby sprawdzić wersję, uruchom
java -version).
Jakie zadania wykonasz
W tym ćwiczeniu uruchomisz i debugujesz prostą aplikację do zakupów online, która korzysta z kilku usług Firebase:
- Cloud Firestore: skalowalna globalnie, bezserwerowa baza danych NoSQL z funkcjami działającymi 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.
Połączysz aplikację z pakietem emulatora, aby umożliwić programowanie lokalne.
Dowiesz się też, jak:
- jak połączyć aplikację z pakietem emulatorów i jak są połączone różne emulatory;
- jak działają reguły zabezpieczeń Firebase i jak testować reguły zabezpieczeń Firestore w lokalnym emulatorze;
- jak napisać funkcję Firebase aktywowaną przez zdarzenia Firestore oraz jak napisać testy integracyjne, które będą uruchamiane w pakiecie emulatora.
2. Skonfiguruj
Pobieranie kodu źródłowego
W tym ćwiczeniu zaczynasz od prawie gotowej wersji przykładowej aplikacji The Fire Store, więc najpierw musisz sklonować kod źródłowy:
$ git clone https://github.com/firebase/emulators-codelab.git
Następnie przejdź do katalogu ćwiczenia, w którym będziesz pracować przez resztę tego ćwiczenia:
$ cd emulators-codelab/codelab-initial-state
Teraz zainstaluj zależności, aby móc uruchomić kod. Jeśli masz wolniejsze połączenie z internetem, 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ą tego polecenia:
$ npm install -g firebase-tools
Następnie sprawdź, czy masz najnowszą wersję interfejsu wiersza poleceń. Ten ćwiczenie 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
Łączenie z projektem w Firebase
Tworzenie projektu w Firebase
- Zaloguj się w konsoli Firebase, korzystając ze swojego konta Google.
- Kliknij przycisk, aby utworzyć nowy projekt, a następnie wpisz jego nazwę (np.
Emulators Codelab).
- Kliknij Dalej.
- Jeśli pojawi się taka prośba, przeczytaj i zaakceptuj Warunki korzystania z Firebase, a następnie kliknij Dalej.
- (Opcjonalnie) Włącz pomoc AI w konsoli Firebase (funkcja „Gemini w Firebase”).
- W tym ćwiczeniu nie potrzebujesz Google Analytics, więc wyłącz tę opcję.
- Kliknij Utwórz projekt, poczekaj na udostępnienie projektu, a następnie kliknij Dalej.
Łączenie kodu z projektem w Firebase
Teraz musimy połączyć ten kod z projektem w Firebase. Najpierw uruchom to polecenie, aby zalogować się w interfejsie wiersza poleceń Firebase:
$ firebase login
Następnie uruchom to polecenie, aby utworzyć alias projektu. Zastąp $YOUR_PROJECT_ID identyfikatorem projektu w Firebase.
$ firebase use $YOUR_PROJECT_ID
Teraz możesz uruchomić aplikację.
3. Uruchamianie emulatorów
W tej sekcji uruchomisz aplikację lokalnie. Oznacza to, że nadszedł czas na uruchomienie pakietu emulatora.
Uruchamianie emulatorów
Aby uruchomić emulatory, w katalogu źródłowym programu CodeLab uruchom to polecenie:
$ firebase emulators:start --import=./seed
Powinny pojawić się wyniki podobne do tych:
$ 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 All emulators started (Wszystkie emulatory zostały uruchomione), aplikacja będzie gotowa do użycia.
Łączenie aplikacji internetowej z emulatorami
Z tabeli w dziennikach wynika, że emulator Cloud Firestore nasłuchuje na porcie 8080, a emulator Authentication – 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 kod frontendu z emulatorem, a nie ze środowiskiem 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/homepage.js
const auth = firebaseApp.auth();
const db = firebaseApp.firestore();
Zaktualizujmy obiekty db i auth, aby wskazywały lokalne emulatory:
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);
}
Teraz, gdy aplikacja działa na komputerze lokalnym (obsługiwanym przez emulator hostingu), klient Firestore również wskazuje lokalny emulator, a nie produkcyjną bazę danych.
Otwieranie interfejsu EmulatorUI
W przeglądarce otwórz stronę http://127.0.0.1:4000/. Powinien pojawić się interfejs pakietu emulatorów.
Kliknij, aby zobaczyć interfejs emulatora Firestore. Kolekcja items zawiera już dane, ponieważ zostały one zaimportowane z flagą --import.
4. Uruchamianie aplikacji
Włącz aplikację
W przeglądarce wejdź na http://127.0.0.1:5000. Powinien wyświetlić się sklep Fire Store działający lokalnie na Twoim komputerze.
Korzystanie z aplikacji
Wybierz produkt na stronie głównej i kliknij Dodaj do koszyka. Wystąpi jednak ten błąd:
Naprawmy ten błąd. Wszystko działa w emulatorach, więc możemy eksperymentować bez obaw o wpływ na rzeczywiste dane.
5. Debugowanie aplikacji
Znajdowanie błędu
Sprawdźmy konsolę dewelopera w Chrome. Naciśnij Control+Shift+J (Windows, Linux, ChromeOS) lub Command+Option+J (Mac), aby zobaczyć błąd w konsoli:
Wygląda na to, że w metodzie addToCart wystąpił błąd. Przyjrzyjmy się temu. W którym miejscu w tej metodzie próbujemy uzyskać dostęp do elementu o nazwie uid i dlaczego może on mieć wartość null? Obecnie metoda wygląda tak w pliku 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);
}
Aha! Nie jesteśmy zalogowani w aplikacji. Zgodnie z dokumentacją Uwierzytelniania Firebase, gdy nie jesteśmy zalogowani, auth.currentUser ma wartość null. Dodajmy odpowiedni test:
public/js/homepage.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ę i kliknij Dodaj do koszyka. Tym razem powinien pojawić się bardziej czytelny błąd:
Jeśli jednak klikniesz Zaloguj się na górnym pasku narzędzi, a potem ponownie klikniesz Dodaj do koszyka, zobaczysz, że koszyk został zaktualizowany.
Wygląda jednak na to, że liczby są zupełnie nieprawidłowe:
Nie martw się, wkrótce naprawimy ten błąd. Najpierw przyjrzyjmy się dokładnie temu, co się stało, gdy dodano produkt do koszyka.
6. Aktywatory funkcji lokalnych
Kliknięcie Dodaj do koszyka uruchamia łańcuch zdarzeń, które obejmują wiele emulatorów. Po dodaniu produktu do koszyka w dziennikach interfejsu wiersza poleceń Firebase powinny pojawić się komunikaty podobne do tych:
i functions: Beginning execution of "calculateCart" i functions: Finished "calculateCart" in ~1s
Te dzienniki i aktualizacja interfejsu, którą widzisz, powstały w wyniku 4 kluczowych zdarzeń:
1) Zapis w Firestore – klient
Do kolekcji Firestore /carts/{cartId}/items/{itemId}/ zostanie dodany nowy dokument. Ten kod możesz zobaczyć w funkcji addToCart w pliku 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) Wywołanie funkcji w Cloud Functions
Funkcja w Cloud Functions calculateCart nasłuchuje wszystkich zdarzeń zapisu (utworzenia, aktualizacji lub usunięcia), które mają miejsce w przypadku produktów w koszyku, za pomocą aktywatora onWrite, który możesz zobaczyć w 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) Firestore Write - Admin
Funkcja calculateCart odczytuje wszystkie produkty w koszyku i sumuje ich łączną liczbę oraz cenę, a następnie aktualizuje dokument „koszyk” o nowe sumy (patrz cartRef.update(...) powyżej).
4) Firestore Read - Client
Frontend internetowy jest subskrybowany, aby otrzymywać aktualizacje o zmianach w koszyku. Po zapisaniu przez funkcję w Cloud Functions nowych sum i zaktualizowaniu interfejsu użytkownika następuje aktualizacja w czasie rzeczywistym, jak widać w public/js/homepage.js:
public/js/homepage.js
this.cartUnsub = cartRef.onSnapshot(cart => {
// The cart document was changed, update the UI
// ...
});
Podsumowanie
Dobra robota! Właśnie skonfigurowano w pełni lokalną aplikację, która używa 3 różnych emulatorów Firebase do testowania w pełni lokalnego.
Poczekaj, to jeszcze nie wszystko. W następnej sekcji dowiesz się:
- jak pisać testy jednostkowe, które korzystają z emulatorów Firebase;
- jak używać emulatorów Firebase do debugowania reguł zabezpieczeń;
7. Tworzenie reguł zabezpieczeń dostosowanych do aplikacji
Nasza aplikacja internetowa odczytuje i zapisuje dane, ale do tej pory nie przejmowaliśmy się bezpieczeństwem. Cloud Firestore używa systemu o nazwie „Reguły zabezpieczeń”, aby określić, kto ma dostęp do odczytu i zapisu danych. Pakiet emulatorów to świetny sposób na prototypowanie tych reguł.
W edytorze otwórz plik emulators-codelab/codelab-initial-state/firestore.rules. Nasze reguły są podzielone na 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;
}
}
}
W tej chwili każdy może odczytywać i zapisywać dane w naszej bazie danych. Chcemy mieć pewność, że przechodzą tylko prawidłowe operacje i nie wyciekają żadne informacje poufne.
W tym ćwiczeniu, zgodnie z zasadą jak najmniejszych uprawnień, zablokujemy wszystkie dokumenty i będziemy stopniowo dodawać dostęp, aż wszyscy użytkownicy będą mieli dostęp, którego potrzebują, ale nie więcej. Zaktualizujmy pierwsze 2 reguły, aby odmawiały 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ń upewnij się, że jesteś w katalogu emulators-codelab/codelab-initial-state/. Emulatory z poprzednich kroków mogą być nadal uruchomione. Jeśli nie, uruchom emulatory ponownie:
$ firebase emulators:start --import=./seed
Po uruchomieniu emulatorów możesz przeprowadzać na nich testy lokalnie.
Przeprowadzanie testów
W wierszu poleceń w nowej karcie terminala z katalogu emulators-codelab/codelab-initial-state/
Najpierw przejdź do katalogu funkcji (pozostaniemy w nim do końca ćwiczenia):
$ 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
Obecnie mamy 4 błędy. Podczas tworzenia pliku reguł możesz mierzyć postępy, obserwując, jak coraz więcej testów kończy się powodzeniem.
9. Bezpieczny dostęp do koszyka
Pierwsze 2 niepowodzenia to testy „koszyka”, które sprawdzają, czy:
- Użytkownicy mogą tworzyć i aktualizować tylko 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());
});
Sprawmy, aby te testy zakończyły się powodzeniem. 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 na dostęp do odczytu i zapisu tylko właścicielowi koszyka.
Aby zweryfikować dane przychodzące i uwierzytelnianie użytkownika, używamy 2 obiektów, które są dostępne w kontekście każdej reguły:
- Obiekt
requestzawiera dane i metadane dotyczące operacji, która jest wykonywana. - Jeśli projekt w Firebase korzysta z Uwierzytelniania Firebase, obiekt
request.authopisuje użytkownika, który wysyła żądanie.
10. Testowanie dostępu do koszyka
Pakiet emulatorów automatycznie aktualizuje reguły po zapisaniu pliku firestore.rules. Aby sprawdzić, czy emulator zaktualizował reguły, na karcie, na której działa emulator, poszukaj komunikatu Rules updated:
Uruchom ponownie testy i sprawdź, czy pierwsze 2 zakończyły się powodzeniem:
$ 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. Sprawdzanie procesu „Dodaj do koszyka” w interfejsie
Obecnie właściciele koszyków mogą odczytywać i zapisywać dane koszyka, ale nie mogą odczytywać ani zapisywać poszczególnych produktów w koszyku. Dzieje się tak, ponieważ właściciele mają dostęp do dokumentu koszyka, ale nie do podkolekcji produktów w koszyku.
To nieprawidłowy stan dla użytkowników.
Wróć do interfejsu internetowego, który działa na http://127.0.0.1:5000,, i spróbuj dodać coś do koszyka. W konsoli debugowania pojawi się błąd Permission Denied, ponieważ nie przyznaliśmy jeszcze użytkownikom dostępu do utworzonych dokumentów w podkolekcji items.
12. Zezwalaj na dostęp do produktów w koszyku
Te 2 testy potwierdzają, że użytkownicy mogą dodawać produkty tylko do własnego koszyka i odczytywać tylko jego zawartość:
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 ownerUID w dokumencie koszyka. Nie musisz określać różnych reguł dla create, update, delete, więc możesz użyć reguły write, która ma zastosowanie do wszystkich żądań modyfikujących dane.
Zaktualizuj regułę dla dokumentów w podkolekcji items. Zmienna get w warunku 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 produktów w koszyku
Teraz możemy ponownie uruchomić test. Przewiń do góry danych wyjściowych i sprawdź, czy więcej testów zakończyło się powodzeniem:
$ 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 kończą się powodzeniem. Mamy jeszcze jeden test, ale zajmiemy się nim za chwilę.
14. Ponownie sprawdź proces „dodawania do koszyka”
Wróć do interfejsu internetowego (http://127.0.0.1:5000) i dodaj produkt do koszyka. To ważny krok, który pozwala potwierdzić, że nasze testy i reguły odpowiadają funkcjom wymaganym przez klienta. (Pamiętaj, że gdy ostatnio testowaliśmy interfejs, użytkownicy nie mogli dodawać produktów do koszyka).
Klient automatycznie ponownie wczytuje reguły po zapisaniu pliku firestore.rules. Spróbuj dodać coś do koszyka.
Podsumowanie
Dobra robota! Właśnie udało Ci się zwiększyć bezpieczeństwo aplikacji, co jest kluczowym krokiem w przygotowaniu jej do wdrożenia w wersji produkcyjnej. Jeśli byłaby to aplikacja produkcyjna, moglibyśmy dodać te testy do potoku ciągłej integracji. Dzięki temu będziemy mieć pewność, że nasze dane koszyka będą objęte tymi mechanizmami kontroli dostępu, nawet jeśli inne osoby będą modyfikować reguły.
To nie wszystko!
Jeśli przejdziesz dalej, dowiesz się:
- jak napisać funkcję aktywowaną przez zdarzenie Firestore,
- Jak tworzyć testy, które działają na wielu emulatorach
15. Konfigurowanie testów Cloud Functions
Do tej pory skupialiśmy się na interfejsie naszej aplikacji internetowej i regułach zabezpieczeń Firestore. Ta aplikacja używa też Cloud Functions do aktualizowania koszyka użytkownika, więc chcemy przetestować również ten kod.
Pakiet emulatorów ułatwia testowanie funkcji Cloud Functions, 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. Obecnie jest oznaczona jako oczekująca:
// 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 początku pliku i zmień ją na rzeczywisty identyfikator projektu w 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. Przegląd testów funkcjonalnych
Ten test sprawdza interakcję między Cloud Firestore i Cloud Functions, dlatego wymaga więcej konfiguracji niż testy w poprzednich modułach. Przyjrzyjmy się temu testowi i zobaczmy, czego on oczekuje.
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ę za pomocą initializeAdminApp zamiast initializeApp. Następnie utwórz DocumentReference dla koszyka, do którego będziemy dodawać produkty, i zainicjuj 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 });
...
});
Aktywowanie funkcji
Następnie dodaj dokumenty do podkolekcji items dokumentu koszyka, aby aktywować funkcję. Dodaj 2 elementy, aby sprawdzić, czy funkcja dodaje je prawidłowo.
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 });
...
});
});
Określanie oczekiwań dotyczących testu
Użyj onSnapshot(), aby zarejestrować detektor zmian w dokumencie koszyka. onSnapshot() zwraca funkcję, którą można wywołać, aby wyrejestrować detektor.
W tym teście dodaj 2 produkty, które razem kosztują 9,98 USD. Następnie sprawdź, czy w koszyku znajdują się oczekiwane wartości 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
Emulatory z poprzednich testów mogą być nadal uruchomione. Jeśli nie, uruchom emulatory. W wierszu poleceń uruchom:
$ firebase emulators:start --import=./seed
Otwórz nową kartę terminala (pozostaw emulatory uruchomione) i przejdź do katalogu funkcji. Możliwe, że masz już otwartą tę kartę po testach reguł zabezpieczeń.
$ cd functions
Teraz uruchom testy jednostkowe. Powinno być ich łącznie 5:
$ 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 przyjrzysz się konkretnemu niepowodzeniu, zobaczysz, że jest to błąd przekroczenia limitu czasu. Dzieje się tak, ponieważ test czeka na prawidłową aktualizację funkcji, która nigdy nie następuje. Teraz możemy napisać funkcję, która przejdzie test.
18. Napisz funkcję
Aby rozwiązać ten problem, musisz zaktualizować funkcję w pliku functions/index.js. Chociaż część tej funkcji jest napisana, nie jest ona kompletna. Funkcja wygląda obecnie 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 iterowanie po
items podkolekcja
Zainicjuj nową stałą itemsSnap, która będzie podkolekcją items. Następnie przejdź przez 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 jako zero.
Następnie dodaj logikę do bloku iteracji. Najpierw sprawdź, czy produkt ma cenę. Jeśli nie określono liczby sztuk, domyślnie zostanie ustawiona wartość 1. Następnie dodaj tę liczbę do sumy bieżącej, która wynosi itemCount. Na koniec dodaj cenę produktu pomnożoną przez ilość do bieżącej sumy wynoszą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 też dodać logowanie, aby ułatwić debugowanie stanów sukcesu 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. Uruchom testy ponownie
W wierszu poleceń sprawdź, czy emulatory nadal działają, i ponownie uruchom testy. Nie musisz ponownie uruchamiać emulatorów, ponieważ automatycznie wykrywają one zmiany w funkcjach. Powinny pojawić się informacje o tym, że wszystkie testy zakończyły się powodzeniem:
$ 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 interfejs Storefront
Aby przeprowadzić ostatni test, wróć do aplikacji internetowej (http://127.0.0.1:5000/) i dodaj produkt do koszyka.
Sprawdź, czy koszyk został zaktualizowany i czy wyświetla się prawidłowa łączna kwota. Fantastycznie!
Podsumowanie
Udało Ci się przejść przez złożony element testowania obejmujący Cloud Functions dla Firebase i Cloud Firestore. napisać funkcję w Cloud Functions, aby test zakończył się powodzeniem; Udało Ci się też potwierdzić, że nowa funkcja działa w interfejsie. Wszystkie te czynności zostały wykonane lokalnie, a emulatory zostały uruchomione na Twoim komputerze.
Utworzyliśmy też klienta internetowego, który działa w lokalnych emulatorach, dostosowaliśmy reguły zabezpieczeń, aby chronić dane, i przetestowaliśmy reguły zabezpieczeń za pomocą lokalnych emulatorów.
