Ikuti semua informasi yang diumumkan di Firebase Summit, dan pelajari bagaimana Firebase dapat membantu Anda mempercepat pengembangan aplikasi dan menjalankan aplikasi dengan percaya diri. Pelajari Lebih Lanjut

Uji Aturan Keamanan Cloud Firestore Anda

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Saat mem-build aplikasi, Anda mungkin ingin mengunci akses ke database Cloud Firestore. Namun, sebelum diluncurkan, Anda memerlukan Aturan Keamanan Cloud Firestore yang lebih bernuansa. Dengan emulator Cloud Firestore, selain membuat prototipe dan menguji fitur dan perilaku umum aplikasi Anda, Anda dapat menulis pengujian unit yang memeriksa perilaku Aturan Keamanan Cloud Firestore Anda.

Mulai cepat

Untuk beberapa kasus pengujian dasar dengan aturan sederhana, cobalah contoh quickstart .

Pahami Aturan Keamanan Cloud Firestore

Terapkan Firebase Authentication dan Aturan Keamanan Cloud Firestore untuk autentikasi tanpa server, otorisasi, dan validasi data saat Anda menggunakan pustaka klien seluler dan web.

Aturan Keamanan Cloud Firestore mencakup dua bagian:

  1. Pernyataan match yang mengidentifikasi dokumen di database Anda.
  2. Ekspresi allow yang mengontrol akses ke dokumen tersebut.

Firebase Authentication memverifikasi kredensial pengguna dan menyediakan fondasi untuk sistem akses berbasis pengguna dan berbasis peran.

Setiap permintaan database dari pustaka klien seluler/web Cloud Firestore dievaluasi berdasarkan aturan keamanan Anda sebelum membaca atau menulis data apa pun. Jika aturan menolak akses ke salah satu jalur dokumen yang ditentukan, seluruh permintaan gagal.

Pelajari Aturan Keamanan Cloud Firestore lebih lanjut di Memulai dengan Aturan Keamanan Cloud Firestore .

Instal emulatornya

Untuk menginstal emulator Cloud Firestore, gunakan Firebase CLI dan jalankan perintah di bawah ini:

firebase setup:emulators:firestore

Jalankan emulator

Mulailah dengan menginisialisasi proyek Firebase di direktori kerja Anda. Ini adalah langkah pertama yang umum saat menggunakan Firebase CLI .

firebase init

Mulai emulator menggunakan perintah berikut. Emulator akan berjalan sampai Anda mematikan prosesnya:

firebase emulators:start --only firestore

Dalam banyak kasus, Anda ingin memulai emulator, menjalankan rangkaian pengujian, lalu mematikan emulator setelah pengujian berjalan. Anda dapat melakukannya dengan mudah menggunakan perintah emulators:exec :

firebase emulators:exec --only firestore "./my-test-script.sh"

Saat dimulai, emulator akan berusaha berjalan pada port default (8080). Anda dapat mengubah port emulator dengan memodifikasi bagian "emulators" pada file firebase.json Anda:

{
  // ...
  "emulators": {
    "firestore": {
      "port": "YOUR_PORT"
    }
  }
}

Sebelum Anda menjalankan emulator

Sebelum Anda mulai menggunakan emulator, ingatlah hal-hal berikut:

  • Emulator awalnya akan memuat aturan yang ditentukan di kolom firestore.rules pada file firebase.json Anda. Itu mengharapkan nama file lokal yang berisi Aturan Keamanan Cloud Firestore Anda dan menerapkan aturan tersebut ke semua project. Jika Anda tidak menyediakan jalur file lokal atau menggunakan metode loadFirestoreRules seperti yang dijelaskan di bawah, emulator akan memperlakukan semua project sebagai aturan terbuka.
  • Meskipun sebagian besar Firebase SDK bekerja dengan emulator secara langsung, hanya @firebase/rules-unit-testing yang mendukung mocking auth di Security Rules, membuat pengujian unit jauh lebih mudah. Selain itu, library mendukung beberapa fitur khusus emulator seperti menghapus semua data, seperti yang tercantum di bawah ini.
  • Emulator juga akan menerima token Firebase Auth produksi yang disediakan melalui SDK Klien dan mengevaluasi aturan yang sesuai, yang memungkinkan menghubungkan aplikasi Anda langsung ke emulator dalam integrasi dan pengujian manual.

Jalankan pengujian unit lokal

Jalankan pengujian unit lokal dengan SDK JavaScript v9

Firebase mendistribusikan pustaka pengujian unit Aturan Keamanan dengan SDK JavaScript versi 9 dan SDK versi 8. API perpustakaan sangat berbeda. Kami merekomendasikan pustaka pengujian v9, yang lebih disederhanakan dan memerlukan lebih sedikit penyiapan untuk terhubung ke emulator sehingga dengan aman menghindari penggunaan sumber daya produksi yang tidak disengaja. Untuk kompatibilitas mundur, kami terus menyediakan pustaka pengujian v8 .

Gunakan @firebase/rules-unit-testing untuk berinteraksi dengan emulator yang berjalan secara lokal. Jika Anda mendapatkan waktu tunggu atau kesalahan ECONNREFUSED , periksa kembali apakah emulator benar-benar berjalan.

Kami sangat menyarankan untuk menggunakan Node.js versi terbaru sehingga Anda dapat menggunakan notasi async/await . Hampir semua perilaku yang mungkin ingin Anda uji melibatkan fungsi asinkron, dan modul pengujian dirancang untuk bekerja dengan kode berbasis Promise.

Pustaka Pengujian Unit Aturan v9 selalu mengetahui emulator dan tidak pernah menyentuh sumber daya produksi Anda.

Anda mengimpor pustaka menggunakan pernyataan impor modular v9. Sebagai contoh:

import {
  assertFails,
  assertSucceeds,
  initializeTestEnvironment,
  RulesTestEnvironment,
} from "@firebase/rules-unit-testing"

// Use `const { … } = require("@firebase/rules-unit-testing")` if imports are not supported
// Or we suggest `const testing = require("@firebase/rules-unit-testing")` if necessary.

Setelah diimpor, pengujian unit implementasi melibatkan:

  • Membuat dan mengonfigurasi RulesTestEnvironment dengan panggilan ke initializeTestEnvironment .
  • Menyiapkan data pengujian tanpa memicu Aturan, menggunakan metode praktis yang memungkinkan Anda mengabaikannya untuk sementara, RulesTestEnvironment.withSecurityRulesDisabled .
  • Menyiapkan test suite dan per-test hook sebelum/sesudah dengan panggilan untuk membersihkan data pengujian dan lingkungan, seperti RulesTestEnvironment.cleanup() atau RulesTestEnvironment.clearFirestore() .
  • Mengimplementasikan kasus pengujian yang meniru status autentikasi menggunakan RulesTestEnvironment.authenticatedContext dan RulesTestEnvironment.unauthenticatedContext .

Metode umum dan fungsi utilitas

Lihat juga metode pengujian khusus emulator di SDK v9 .

initializeTestEnvironment() => RulesTestEnvironment

Fungsi ini menginisialisasi lingkungan pengujian untuk pengujian unit aturan. Panggil fungsi ini terlebih dahulu untuk penyiapan pengujian. Eksekusi yang berhasil membutuhkan emulator untuk berjalan.

Fungsi menerima objek opsional yang mendefinisikan TestEnvironmentConfig , yang dapat terdiri dari project ID dan setelan konfigurasi emulator.

let testEnv = await initializeTestEnvironment({
  projectId: "demo-project-1234",
  firestore: {
    rules: fs.readFileSync("firestore.rules", "utf8"),
  },
});

RulesTestEnvironment.authenticatedContext({ user_id: string, tokenOptions?: TokenOptions }) => RulesTestContext

Metode ini membuat RulesTestContext , yang berperilaku seperti pengguna Otentikasi yang diautentikasi. Permintaan yang dibuat melalui konteks yang dikembalikan akan memiliki token Otentikasi tiruan yang dilampirkan. Secara opsional, berikan objek yang mendefinisikan klaim khusus atau penggantian untuk payload token Otentikasi.

Gunakan objek konteks pengujian yang dikembalikan dalam pengujian Anda untuk mengakses semua instance emulator yang dikonfigurasi, termasuk yang dikonfigurasi dengan initializeTestEnvironment .

// Assuming a Firestore app and the Firestore emulator for this example
import { setDoc } from "firebase/firestore";

const alice = testEnv.authenticatedContext("alice", { … });
// Use the Firestore instance associated with this context
await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

RulesTestEnvironment.unauthenticatedContext() => RulesTestContext

Metode ini membuat RulesTestContext , yang berperilaku seperti klien yang tidak masuk melalui Otentikasi. Permintaan yang dibuat melalui konteks yang dikembalikan tidak akan menyertakan token Firebase Auth.

Gunakan objek konteks pengujian yang dikembalikan dalam pengujian Anda untuk mengakses semua instance emulator yang dikonfigurasi, termasuk yang dikonfigurasi dengan initializeTestEnvironment .

// Assuming a Cloud Storage app and the Storage emulator for this example
import { getStorage, ref, deleteObject } from "firebase/storage";

const alice = testEnv.unauthenticatedContext();

// Use the Cloud Storage instance associated with this context
const desertRef = ref(alice.storage(), 'images/desert.jpg');
await assertSucceeds(deleteObject(desertRef));

RulesTestEnvironment.withSecurityRulesDisabled()

Jalankan fungsi penyiapan pengujian dengan konteks yang berperilaku seolah-olah Aturan Keamanan dinonaktifkan.

Metode ini menggunakan fungsi callback, yang mengambil konteks melewati Aturan Keamanan dan mengembalikan sebuah janji. Konteksnya akan dihancurkan setelah janji diselesaikan/ditolak.

RulesTestEnvironment.cleanup()

Metode ini menghancurkan semua RulesTestContexts dibuat di lingkungan pengujian dan membersihkan sumber daya yang mendasarinya, memungkinkan keluar yang bersih.

Metode ini tidak mengubah status emulator dengan cara apa pun. Untuk menyetel ulang data di antara pengujian, gunakan metode hapus data khusus emulator aplikasi.

assertSucceeds(pr: Promise<any>)) => Promise<any>

Ini adalah fungsi utilitas kasus uji.

Fungsi menegaskan bahwa Janji yang disertakan yang membungkus operasi emulator akan diselesaikan tanpa pelanggaran Aturan Keamanan.

await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

assertFails(pr: Promise<any>)) => Promise<any>

Ini adalah fungsi utilitas kasus uji.

Fungsi menegaskan bahwa Janji yang disertakan yang membungkus operasi emulator akan ditolak dengan pelanggaran Aturan Keamanan.

await assertFails(setDoc(alice.firestore(), '/users/bob'), { ... });

Metode khusus emulator

Lihat juga metode pengujian umum dan fungsi utilitas di SDK v9 .

RulesTestEnvironment.clearFirestore() => Promise<void>

Metode ini menghapus data di database Firestore milik projectId yang dikonfigurasi untuk emulator Firestore.

RulesTestContext.firestore(settings?: Firestore.FirestoreSettings) => Firestore;

Metode ini mendapatkan instance Firestore untuk konteks pengujian ini. Instance Firebase JS Client SDK yang dikembalikan dapat digunakan dengan klien SDK API (v9 modular atau v9 compat).

Visualisasikan evaluasi aturan

Emulator Cloud Firestore memungkinkan Anda memvisualisasikan permintaan klien di UI Emulator Suite, termasuk pelacakan evaluasi untuk Aturan Keamanan Firebase.

Buka tab Firestore > Permintaan untuk melihat urutan evaluasi mendetail untuk setiap permintaan.

Pemantauan Permintaan Emulator Firestore menampilkan evaluasi Aturan Keamanan

Menghasilkan laporan pengujian

Setelah menjalankan rangkaian pengujian, Anda dapat mengakses laporan cakupan pengujian yang menunjukkan bagaimana setiap aturan keamanan Anda dievaluasi.

Untuk mendapatkan laporan, kueri endpoint yang terekspos pada emulator saat sedang berjalan. Untuk versi ramah browser, gunakan URL berikut:

http://localhost:8080/emulator/v1/projects/<project_id>:ruleCoverage.html

Ini memecah aturan Anda menjadi ekspresi dan subekspresi yang dapat Anda arahkan dengan mouse untuk informasi lebih lanjut, termasuk jumlah evaluasi dan nilai yang dikembalikan. Untuk versi JSON mentah dari data ini, sertakan URL berikut dalam kueri Anda:

http://localhost:8080/emulator/v1/projects/<project_id>:ruleCoverage

Perbedaan antara emulator dan produksi

  1. Anda tidak perlu membuat project Cloud Firestore secara eksplisit. Emulator secara otomatis membuat instance apa pun yang diakses.
  2. Emulator Cloud Firestore tidak berfungsi dengan aliran Firebase Authentication normal. Sebagai gantinya, di Firebase Test SDK, kami telah menyediakan metode initializeTestApp() di library rules-unit-testing , yang menggunakan kolom auth . Pegangan Firebase yang dibuat menggunakan metode ini akan berperilaku seolah-olah telah berhasil diautentikasi sebagai entitas apa pun yang Anda berikan. Jika Anda memasukkan null , itu akan berperilaku sebagai pengguna yang tidak diautentikasi ( aturan auth != null akan gagal, misalnya).

Pecahkan masalah umum

Saat menggunakan emulator Cloud Firestore, Anda mungkin mengalami masalah umum berikut. Ikuti panduan di bawah ini untuk memecahkan masalah perilaku tidak biasa yang Anda alami. Catatan ini ditulis dengan mempertimbangkan pustaka pengujian unit Aturan Keamanan, tetapi pendekatan umum berlaku untuk SDK Firebase apa pun.

Perilaku pengujian tidak konsisten

Jika pengujian Anda kadang-kadang lulus dan gagal, bahkan tanpa perubahan apa pun pada pengujian itu sendiri, Anda mungkin perlu memverifikasi bahwa pengujian tersebut diurutkan dengan benar. Sebagian besar interaksi dengan emulator bersifat asinkron, jadi periksa kembali apakah semua kode asinkron telah diurutkan dengan benar. Anda dapat memperbaiki pengurutan dengan merangkai janji, atau menggunakan notasi await secara bebas.

Khususnya, tinjau operasi asinkron berikut:

  • Menetapkan aturan keamanan, misalnya dengan initializeTestEnvironment .
  • Membaca dan menulis data, dengan, misalnya, db.collection("users").doc("alice").get() .
  • Penegasan operasional, termasuk assertSucceeds dan assertFails .

Pengujian hanya lulus saat pertama kali Anda memuat emulator

Emulator adalah stateful. Itu menyimpan semua data yang ditulis ke dalam memori, jadi data apa pun hilang setiap kali emulator dimatikan. Jika Anda menjalankan beberapa pengujian terhadap id proyek yang sama, setiap pengujian dapat menghasilkan data yang mungkin memengaruhi pengujian berikutnya. Anda dapat menggunakan salah satu metode berikut untuk menghindari perilaku ini:

  • Gunakan ID proyek unik untuk setiap pengujian. Perhatikan bahwa jika Anda memilih untuk melakukan ini, Anda perlu memanggil initializeTestEnvironment sebagai bagian dari setiap pengujian; aturan hanya dimuat secara otomatis untuk project ID default.
  • Susun ulang pengujian Anda agar tidak berinteraksi dengan data yang ditulis sebelumnya (misalnya, gunakan koleksi yang berbeda untuk setiap pengujian).
  • Hapus semua data yang ditulis selama tes.

Penyiapan tes sangat rumit

Saat menyiapkan pengujian, Anda mungkin ingin mengubah data dengan cara yang sebenarnya tidak diizinkan oleh Aturan Keamanan Cloud Firestore Anda. Jika aturan Anda membuat penyiapan pengujian menjadi rumit, coba gunakan RulesTestEnvironment.withSecurityRulesDisabled di langkah penyiapan Anda, jadi baca dan tulis tidak akan memicu kesalahan PERMISSION_DENIED .

Setelah itu, pengujian Anda dapat melakukan operasi sebagai pengguna yang diautentikasi atau tidak diautentikasi masing-masing menggunakan RulesTestEnvironment.authenticatedContext dan unauthenticatedContext . Ini memungkinkan Anda untuk memvalidasi bahwa Aturan Keamanan Cloud Firestore Anda mengizinkan/menolak berbagai kasus dengan benar.