Pengembangan Lokal dengan Firebase Emulator Suite

1. Sebelum memulai

Alat backend serverless seperti Cloud Firestore dan Cloud Functions sangat mudah digunakan, tetapi dapat sulit diuji. Firebase Local Emulator Suite memungkinkan Anda menjalankan versi lokal layanan ini di mesin pengembangan sehingga Anda dapat mengembangkan aplikasi dengan cepat dan aman.

Prasyarat

• Editor sederhana seperti Visual Studio Code, Atom, atau Sublime Text
• Node.js 10.0.0 atau yang lebih tinggi (untuk menginstal Node.js, gunakan nvm, untuk memeriksa versi Anda, jalankan node --version)
• Java 7 atau yang lebih tinggi (untuk menginstal Java gunakan petunjuk ini, untuk memeriksa versi Anda, jalankan java -version)

Yang akan Anda lakukan

Dalam codelab ini, Anda akan menjalankan dan men-debug aplikasi belanja online sederhana yang didukung oleh beberapa layanan Firebase:

• Cloud Firestore: database NoSQL tanpa server yang skalabel secara global dengan kemampuan real-time.
• Cloud Functions: kode backend serverless yang berjalan sebagai respons terhadap peristiwa atau permintaan HTTP.
• Firebase Authentication: layanan autentikasi terkelola yang terintegrasi dengan produk Firebase lainnya.
• Firebase Hosting: hosting yang cepat dan aman untuk aplikasi web.

Anda akan menghubungkan aplikasi ke Emulator Suite untuk mengaktifkan pengembangan lokal.

Anda juga akan mempelajari cara:

• Cara menghubungkan aplikasi ke Emulator Suite dan cara berbagai emulator terhubung.
• Cara kerja Aturan Keamanan Firebase dan cara menguji Aturan Keamanan Firestore terhadap emulator lokal.
• Cara menulis Firebase Function yang dipicu oleh peristiwa Firestore dan cara menulis pengujian integrasi yang dijalankan terhadap Emulator Suite.

2. Siapkan

Mendapatkan kode sumber

Dalam codelab ini, Anda akan memulai dengan versi contoh Fire Store yang hampir selesai, jadi hal pertama yang perlu Anda lakukan adalah meng-clone kode sumber:

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

Kemudian, pindahkan ke direktori codelab, tempat Anda akan bekerja selama sisa codelab ini:

$ cd emulators-codelab/codelab-initial-state

Sekarang, instal dependensi sehingga Anda dapat menjalankan kodenya. Jika Anda menggunakan koneksi internet yang lebih lambat, proses ini mungkin memerlukan waktu satu atau dua menit:

# Move into the functions directory
$ cd functions

# Install dependencies
$ npm install

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

Mendapatkan Firebase CLI

Emulator Suite adalah bagian dari Firebase CLI (antarmuka command line) yang dapat diinstal di komputer Anda dengan perintah berikut:

$ npm install -g firebase-tools

Selanjutnya, pastikan Anda memiliki CLI versi terbaru. Codelab ini seharusnya berfungsi dengan versi 9.0.0 atau yang lebih tinggi, tetapi versi yang lebih baru menyertakan lebih banyak perbaikan bug.

$ firebase --version
9.6.0

Hubungkan ke project Firebase Anda

Jika Anda belum memiliki project Firebase, di Firebase console, buat project Firebase baru. Catat Project ID yang Anda pilih, Anda akan memerlukannya nanti.

Sekarang kita perlu menghubungkan kode ini ke project Firebase Anda. Pertama, jalankan perintah berikut untuk login ke Firebase CLI:

$ firebase login

Selanjutnya, jalankan perintah berikut untuk membuat alias project. Ganti $YOUR_PROJECT_ID dengan ID project Firebase Anda.

$ firebase use $YOUR_PROJECT_ID

Sekarang Anda siap menjalankan aplikasi.

3. Menjalankan emulator

Di bagian ini, Anda akan menjalankan aplikasi secara lokal. Artinya, sekarang saatnya mem-booting Emulator Suite.

Memulai Emulator

Dari dalam direktori sumber codelab, jalankan perintah berikut untuk memulai emulator:

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

Anda akan melihat output seperti ini:

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

Setelah Anda melihat pesan Semua emulator dimulai, aplikasi siap digunakan.

Catatan: Apa yang baru saja terjadi?

• Setiap emulator dimulai di 127.0.0.1, dan setiap emulator berjalan di port yang berbeda.
• Emulator Firestore mengimpor data dari direktori seed, yang disediakan untuk mempermudah codelab ini.
• Emulator Functions melihat fungsi calculateCart dan memberi tahu emulator Firestore.
• Emulator Functions kini memantau direktori functions untuk melihat perubahan kode.

Menghubungkan aplikasi web ke emulator

Berdasarkan tabel dalam log, kita dapat melihat bahwa emulator Cloud Firestore memproses port 8080 dan emulator Authentication memproses port 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                             │
└────────────────┴────────────────┴─────────────────────────────────┘

Mari kita hubungkan kode frontend Anda ke emulator, bukan ke produksi. Buka file public/js/homepage.js dan temukan fungsi onDocumentReady. Kita dapat melihat bahwa kode tersebut mengakses instance Firestore dan Auth standar:

public/js/homepage.js

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

Mari kita update objek db dan auth agar mengarah ke emulator lokal:

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

Sekarang, saat aplikasi berjalan di komputer lokal Anda (disajikan oleh emulator Hosting), klien Firestore juga mengarah ke emulator lokal, bukan ke database produksi.

Membuka EmulatorUI

Di browser web, buka http://127.0.0.1:4000/. Anda akan melihat UI Emulator Suite.

Klik untuk melihat UI untuk Emulator Firestore. Koleksi items sudah berisi data karena data diimpor dengan tanda --import.

4. Menjalankan aplikasi

Buka aplikasi

Di browser web Anda, buka http://127.0.0.1:5000 dan Anda akan melihat The Fire Store berjalan secara lokal di komputer Anda!

Menggunakan aplikasi

Pilih item di halaman beranda dan klik Tambahkan ke Keranjang. Sayangnya, Anda akan mengalami error berikut:

Mari kita perbaiki bug tersebut. Karena semuanya berjalan di emulator, kita dapat bereksperimen dan tidak perlu khawatir akan memengaruhi data yang sebenarnya.

5. Men-debug aplikasi

Temukan bug

Baik, mari kita lihat di konsol developer Chrome. Tekan Control+Shift+J (Windows, Linux, Chrome OS) atau Command+Option+J (Mac) untuk melihat error di konsol:

Sepertinya ada beberapa error dalam metode addToCart, mari kita lihat. Di mana kita mencoba mengakses sesuatu yang disebut uid dalam metode tersebut dan mengapa itu menjadi null? Saat ini, metodenya terlihat seperti ini di public/js/homepage.js:

public/js/homepage.js

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

Aha! Kita tidak login ke aplikasi. Menurut dokumen Firebase Authentication, saat kita tidak login, auth.currentUser adalah null. Mari kita tambahkan pemeriksaan untuk hal tersebut:

public/js/homepage.js

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

    // ...
  }

Menguji aplikasi

Sekarang, muat ulang halaman, lalu klik Tambahkan ke Keranjang. Kali ini Anda akan mendapatkan error yang lebih baik:

Namun, jika Anda mengklik Login di toolbar bagian atas, lalu mengklik Tambahkan ke Keranjang lagi, Anda akan melihat bahwa keranjang telah diperbarui.

Catatan: Untuk tujuan demonstrasi, aplikasi ini secara eksklusif menggunakan Autentikasi Anonim. Autentikasi Anonim menetapkan ID yang mengidentifikasi pengguna secara unik ke backend untuk setiap pengguna sesi. Hal ini memungkinkan Anda membuat pengalaman orientasi yang tidak mengharuskan pengguna untuk segera membuat akun permanen. Di aplikasi produksi, untuk menyimpan data pengguna di seluruh sesi dan perangkat, Anda harus mengonversi pengguna dari Autentikasi Anonim ke metode login lain.

Namun, sepertinya angka tersebut sama sekali tidak benar:

Jangan khawatir, kami akan segera memperbaiki bug tersebut. Pertama, mari kita pelajari lebih dalam apa yang sebenarnya terjadi saat Anda menambahkan item ke keranjang.

6. Pemicu fungsi lokal

Mengklik Tambahkan ke Keranjang akan memulai rantai peristiwa yang melibatkan beberapa emulator. Di log Firebase CLI, Anda akan melihat pesan seperti berikut setelah menambahkan item ke keranjang:

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

Ada empat peristiwa utama yang terjadi untuk menghasilkan log tersebut dan pembaruan UI yang Anda amati:

Catatan: Anda tidak perlu mengupdate aplikasi dengan cuplikan kode di bawah. Kode sudah disertakan dalam aplikasi. Cuplikan kode di bagian ini hanya disajikan untuk membantu Anda memahami empat peristiwa utama.

1) Penulisan Firestore - Klien

Dokumen baru ditambahkan ke koleksi Firestore /carts/{cartId}/items/{itemId}/. Anda dapat melihat kode ini di fungsi addToCart di dalam 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) Cloud Function Dipicu

calculateCart Cloud Function memproses peristiwa tulis (membuat, memperbarui, atau menghapus) yang terjadi pada item keranjang menggunakan pemicu onWrite, yang dapat Anda lihat di 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) Penulisan Firestore - Admin

Fungsi calculateCart membaca semua item dalam keranjang dan menjumlahkan total kuantitas dan harga, lalu memperbarui "keranjang" dokumen dengan total baru (lihat cartRef.update(...) di atas).

4) Pembacaan Firestore - Klien

Frontend web berlangganan untuk menerima info terbaru tentang perubahan pada keranjang. Fungsi ini mendapatkan update real-time setelah Cloud Function menulis total baru dan mengupdate UI, seperti yang dapat Anda lihat di public/js/homepage.js:

public/js/homepage.js

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

Rangkuman

Bagus! Anda baru saja menyiapkan aplikasi sepenuhnya lokal yang menggunakan tiga emulator Firebase berbeda untuk pengujian sepenuhnya lokal.

Tunggu, masih ada lagi! Di bagian berikutnya, Anda akan mempelajari:

• Cara menulis pengujian unit yang menggunakan Emulator Firebase.
• Cara menggunakan Emulator Firebase untuk men-debug Aturan Keamanan Anda.

7. Membuat aturan keamanan yang disesuaikan untuk aplikasi Anda

Aplikasi web kami membaca dan menulis data, tetapi sejauh ini kami tidak terlalu khawatir dengan keamanan. Cloud Firestore menggunakan sistem yang disebut "Aturan Keamanan" untuk mendeklarasikan siapa yang memiliki akses untuk membaca dan menulis data. Emulator Suite adalah cara yang bagus untuk membuat prototipe aturan ini.

Di editor, buka file emulators-codelab/codelab-initial-state/firestore.rules. Anda akan melihat bahwa kita memiliki tiga bagian utama dalam aturan:

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

Saat ini, siapa saja dapat membaca dan menulis data ke database kita. Kami ingin memastikan bahwa hanya operasi yang valid yang lolos dan kami tidak membocorkan informasi sensitif apa pun.

Selama codelab ini, dengan mengikuti Prinsip Hak Istimewa Terendah, kita akan mengunci semua dokumen dan menambahkan akses secara bertahap hingga semua pengguna memiliki semua akses yang mereka butuhkan, tetapi tidak lebih. Mari kita perbarui dua aturan pertama untuk menolak akses dengan menyetel kondisi ke 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;
    }
  }
}

Catatan: Bagaimana jika tidak ada pernyataan kecocokan untuk suatu operasi?

• Aturan menolak secara default. Jika operasi tidak cocok dengan aturan apa pun yang ditetapkan dalam file aturan, akses akan ditolak.
• Mode terkunci, atau mode Produksi, membuat penolakan implisit menjadi penolakan eksplisit dengan mencocokkan semua dokumen dan menolak semua akses.

8. Menjalankan emulator dan pengujian

Memulai emulator

Di command line, pastikan Anda berada di emulators-codelab/codelab-initial-state/. Emulator tersebut mungkin masih berjalan dari langkah sebelumnya. Jika tidak, mulai ulang emulator:

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

Setelah emulator berjalan, Anda dapat menjalankan pengujian secara lokal terhadapnya.

Menjalankan pengujian

Di command line di tab terminal baru dari direktori emulators-codelab/codelab-initial-state/

Pertama, buka direktori fungsi (kita akan tetap berada di sini selama sisa codelab):

$ cd functions

Sekarang, jalankan pengujian mocha di direktori fungsi, lalu scroll ke bagian atas output:

# Run the tests
$ npm test

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

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

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

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


  0 passing (364ms)
  1 pending
  4 failing

Saat ini kita memiliki empat kegagalan. Saat membuat file aturan, Anda dapat mengukur progres dengan melihat lebih banyak pengujian yang lulus.

9. Mengamankan akses keranjang

Dua kegagalan pertama adalah "keranjang belanja" pengujian yang menguji bahwa:

• Pengguna hanya dapat membuat dan memperbarui keranjang mereka sendiri
• Pengguna hanya dapat membaca keranjang mereka sendiri

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

Mari kita buat pengujian ini lulus. Di editor, buka file aturan keamanan, firestore.rules, lalu perbarui pernyataan dalam 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;
    }

    // ...
  }
}

Aturan ini sekarang hanya mengizinkan akses baca dan tulis oleh pemilik keranjang.

Untuk memverifikasi data yang masuk dan autentikasi pengguna, kami menggunakan dua objek yang tersedia dalam konteks setiap aturan:

• Objek request berisi data dan metadata tentang operasi yang sedang dicoba.
• Jika project Firebase menggunakan Firebase Authentication, objek request.auth akan menjelaskan pengguna yang membuat permintaan.

Apa perbedaan utama antara resource dan request.resource****?

• resource: Merepresentasikan dokumen Firestore yang dipermasalahkan sebelum permintaan saat ini. Jadi, untuk permintaan create, resource.data selalu null karena dokumen belum ada.
• request.resource: Menampilkan dokumen Firestore dengan perubahan yang ingin ditulis pengguna. Jadi, untuk permintaan buat, request.resource.data berisi dokumen yang diusulkan.

10. Menguji akses keranjang

Emulator Suite otomatis memperbarui aturan setiap kali firestore.rules disimpan. Anda dapat mengonfirmasi bahwa emulator telah memperbarui aturan dengan melihat pesan Rules updated di tab yang menjalankan emulator:

Jalankan kembali pengujian, dan pastikan dua pengujian pertama sekarang lulus:

$ 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

Bagus! Anda kini telah mengamankan akses ke keranjang belanja. Mari kita lanjutkan ke pengujian yang gagal berikutnya.

11. Memeriksa alur "Tambahkan ke Keranjang" di UI

Saat ini, meskipun pemilik keranjang membaca dan menulis ke keranjang, mereka tidak dapat membaca atau menulis item individual di keranjang mereka. Ini karena meskipun pemilik memiliki akses ke dokumen keranjang, mereka tidak memiliki akses ke subkoleksi item keranjang.

Selain itu: Aturan tidak menurun melalui subkoleksi

• Secara default, aturan untuk dokumen tidak menurun ke dokumen dalam subkoleksi.
• Biasanya, Anda menginginkan aturan yang sedikit berbeda untuk dokumen dalam subkoleksi.
• Jika Anda ingin dokumen dalam subkoleksi memiliki aturan yang sama persis, Anda dapat menggunakan sintaksis glob untuk mencocokkan semua dokumen secara rekursif: match /{cartId=**} (lakukan dengan hati-hati).

Ini adalah status yang rusak bagi pengguna.

Kembali ke UI web, yang berjalan di http://127.0.0.1:5000,, dan coba tambahkan sesuatu ke keranjang Anda. Anda mendapatkan error Permission Denied, yang terlihat dari konsol debug, karena kami belum memberi pengguna akses ke dokumen yang dibuat di subkoleksi items.

12. Izinkan akses item keranjang

Kedua pengujian ini mengonfirmasi bahwa pengguna hanya dapat menambahkan item ke atau membaca item dari keranjang mereka sendiri:

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

Jadi, kita dapat menulis aturan yang mengizinkan akses jika pengguna saat ini memiliki UID yang sama dengan ownerUID di dokumen keranjang. Karena tidak perlu menentukan aturan yang berbeda untuk create, update, delete, Anda dapat menggunakan aturan write, yang berlaku untuk semua permintaan yang mengubah data.

Perbarui aturan untuk dokumen di subkoleksi item. get dalam kondisional membaca nilai dari Firestore–dalam hal ini, ownerUID pada dokumen keranjang.

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

    // ...
  }
}

Catatan: Kapan Anda dapat menggunakan resource atau melakukan panggilan get?

• Anda dapat menggunakan objek resource jika data yang diperlukan adalah bagian dari dokumen saat ini yang sedang dibaca/ditulis.
• Jika Anda memerlukan data di luar dokumen saat ini, gunakan pernyataan get. Perlu diperhatikan bahwa operasi ini diperhitungkan dalam tagihan Firestore Anda.

13. Menguji akses item keranjang

Sekarang kita dapat menjalankan kembali pengujiannya. Scroll ke bagian atas output dan periksa apakah lebih banyak pengujian yang lulus:

$ 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

Bagus! Sekarang semua pengujian kita lulus. Ada satu pengujian yang masih tertunda, tetapi kami akan melakukannya dalam beberapa langkah.

14. Periksa kembali alur "tambahkan ke keranjang"

Kembali ke front end web ( http://127.0.0.1:5000) dan tambahkan item ke keranjang. Ini adalah langkah penting untuk memastikan bahwa pengujian dan aturan kami sesuai dengan fungsi yang diperlukan oleh klien. (Ingat bahwa terakhir kali kita mencoba UI, pengguna tidak dapat menambahkan item ke keranjang mereka!)

Klien akan otomatis memuat ulang aturan saat firestore.rules disimpan. Jadi, coba tambahkan sesuatu ke keranjang.

Rangkuman

Bagus! Anda baru saja meningkatkan keamanan aplikasi, yang merupakan langkah penting untuk menyiapkannya untuk produksi. Jika ini adalah aplikasi produksi, kita dapat menambahkan pengujian ini ke pipeline continuous integration. Hal ini akan memberi kami keyakinan ke depannya bahwa data keranjang belanja kami akan memiliki kontrol akses ini, meskipun orang lain mengubah aturannya.

Tapi tunggu, masih ada lagi.

jika Anda melanjutkan, Anda akan mempelajari:

• Cara menulis fungsi yang dipicu oleh peristiwa Firestore
• Cara membuat pengujian yang berfungsi di beberapa emulator

15. Menyiapkan pengujian Cloud Functions

Sejauh ini, kita telah berfokus pada frontend aplikasi web dan Aturan Keamanan Firestore. Namun, aplikasi ini juga menggunakan Cloud Functions untuk memastikan keranjang pengguna selalu diperbarui, jadi kita juga ingin menguji kode itu.

Emulator Suite memudahkan pengujian Cloud Functions, bahkan fungsi yang menggunakan Cloud Firestore dan layanan lainnya.

Di editor, buka file emulators-codelab/codelab-initial-state/functions/test.js dan scroll ke pengujian terakhir dalam file. Saat ini, permintaan tersebut ditandai sebagai tertunda:

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

Untuk mengaktifkan pengujian, hapus .skip, sehingga terlihat seperti ini:

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

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

Selanjutnya, temukan variabel REAL_FIREBASE_PROJECT_ID di bagian atas file dan ubah menjadi Project ID Firebase yang sebenarnya.:

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

Jika lupa project ID, Anda dapat menemukan Project ID Firebase di Setelan Project di Firebase Console:

16. Mempelajari pengujian Functions

Karena pengujian ini memvalidasi interaksi antara Cloud Firestore dan Cloud Functions, pengujian ini memerlukan lebih banyak penyiapan daripada pengujian di codelab sebelumnya. Mari kita jalankan pengujian ini dan pahami apa yang diharapkan.

Catatan: Cuplikan kode di bawah dimaksudkan untuk membantu Anda membaca dan memahami kode yang sudah ditulis. Pada langkah ini, Anda tidak perlu mengubah aplikasi sama sekali.

Membuat keranjang

Cloud Functions berjalan di lingkungan server tepercaya dan dapat menggunakan autentikasi akun layanan yang digunakan oleh Admin SDK. Pertama, Anda melakukan inisialisasi aplikasi menggunakan initializeAdminApp, bukan initializeApp. Kemudian, Anda membuat DocumentReference untuk keranjang tempat kita akan menambahkan item dan melakukan inisialisasi keranjang:

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

    ...
  });

Memicu fungsi

Kemudian, tambahkan dokumen ke subkoleksi items dari dokumen keranjang untuk memicu fungsi. Tambahkan dua item untuk memastikan Anda menguji penambahan yang terjadi dalam fungsi.

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

    ...
    });
  });

Menetapkan ekspektasi pengujian

Gunakan onSnapshot() untuk mendaftarkan pemroses perubahan pada dokumen keranjang. onSnapshot() menampilkan fungsi yang dapat Anda panggil untuk membatalkan pendaftaran pemroses.

Mengapa memproses dokumen keranjang, bukan dokumen dalam subkoleksi item?

Meskipun fungsi dipicu oleh operasi tulis di subkoleksi items, fungsi tersebut kemudian akan memperbarui dokumen keranjang. Itu adalah efek samping dari penulisan awal yang ingin kita uji.

Untuk pengujian ini, tambahkan dua item yang harganya $9,98. Kemudian, periksa apakah keranjang memiliki itemCount dan totalPrice yang diharapkan. Jika ya, maka fungsi tersebut telah melakukan tugasnya.

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. Menjalankan pengujian

Emulator mungkin masih berjalan dari pengujian sebelumnya. Jika tidak, mulai emulator. Dari baris perintah, jalankan

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

Buka tab terminal baru (biarkan emulator berjalan) dan pindahkan ke direktori fungsi. Anda mungkin masih memiliki kunci ini terbuka dari pengujian aturan keamanan.

$ cd functions

Sekarang jalankan pengujian unit, Anda akan melihat 5 total pengujian:

$ 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

Jika Anda melihat kegagalan tertentu, tampaknya itu adalah error waktu tunggu habis. Hal ini karena pengujian menunggu fungsi diperbarui dengan benar, tetapi tidak pernah diperbarui. Sekarang, kita siap menulis fungsi untuk memenuhi pengujian.

18. Tulis fungsi

Untuk memperbaiki pengujian ini, Anda perlu mengupdate fungsi di functions/index.js. Meskipun beberapa fungsi ini sudah ditulis, ini tidak lengkap. Seperti inilah tampilan fungsi saat ini:

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

Fungsi ini menetapkan referensi keranjang dengan benar, tetapi alih-alih menghitung nilai totalPrice dan itemCount, fungsi akan memperbaruinya menjadi nilai hardcode.

Ambil dan iterasi melalui

items subkoleksi

Lakukan inisialisasi konstanta baru, itemsSnap, untuk menjadi subkoleksi items. Kemudian, lakukan iterasi di seluruh dokumen dalam koleksi.

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

Menghitung totalPrice dan itemCount

Pertama, mari kita inisialisasi nilai totalPrice dan itemCount ke nol.

Kemudian, tambahkan logika ke blok iterasi. Pertama, pastikan item memiliki harga. Jika item tidak memiliki jumlah yang ditentukan, tetapkan secara default ke 1. Kemudian, tambahkan kuantitas ke total berjalan itemCount. Terakhir, tambahkan harga item yang dikalikan dengan kuantitas ke total berjalan 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) {
      }
    });

Anda juga dapat menambahkan logging untuk membantu proses debug status keberhasilan dan error:

// 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. Jalankan kembali pengujian

Di command line, pastikan emulator masih berjalan dan jalankan ulang pengujian. Anda tidak perlu memulai ulang emulator karena emulator akan otomatis mengambil perubahan pada fungsi. Anda akan melihat semua pengujian lulus:

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

Bagus!

20. Coba gunakan UI Etalase

Untuk pengujian akhir, kembali ke aplikasi web ( http://127.0.0.1:5000/) dan tambahkan item ke keranjang.

Pastikan keranjang diperbarui dengan jumlah total yang benar. Terima kasih.

Rangkuman

Anda telah mempelajari kasus pengujian yang kompleks antara Cloud Functions for Firebase dan Cloud Firestore. Anda telah menulis Cloud Function agar pengujian berhasil. Anda juga mengonfirmasi bahwa fungsi baru berfungsi di UI. Anda melakukan semua ini secara lokal, menjalankan emulator di komputer Anda sendiri.

Anda juga telah membuat klien web yang dijalankan pada emulator lokal, menyesuaikan aturan keamanan untuk melindungi data, dan menguji aturan keamanan menggunakan emulator lokal.