Menghubungkan aplikasi ke Emulator Cloud Firestore

Sebelum menghubungkan aplikasi ke emulator Cloud Firestore, pastikan Anda memahami keseluruhan alur kerja Firebase Local Emulator Suite, dan sudah menginstal serta mengonfigurasi Local Emulator Suite dan mengetahui perintah CLI-nya.

Memilih project Firebase

Firebase Local Emulator Suite mengemulasi produk untuk satu project Firebase.

Untuk memilih project yang akan digunakan, sebelum memulai emulator, jalankan firebase use di CLI di direktori kerja Anda. Atau, Anda dapat meneruskan flag --project ke setiap perintah emulator.

Local Emulator Suite mendukung emulasi project Firebase sungguhan dan project demo.

Jenis project Fitur Penggunaan dengan emulator
Sungguhan

Project Firebase sungguhan adalah project yang Anda buat dan konfigurasikan (kemungkinan besar melalui Firebase console).

Project sungguhan memiliki resource live, seperti instance database, bucket penyimpanan, fungsi, atau resource lain yang Anda siapkan untuk project Firebase tersebut.

Jika mengerjakan project Firebase sungguhan, Anda dapat menjalankan emulator untuk salah satu atau semua produk yang didukung.

Untuk produk yang tidak diemulasi, aplikasi dan kode Anda akan berinteraksi dengan resource live (instance database, bucket penyimpanan, fungsi, dsb.).

Demo

Project Firebase demo tidak memiliki konfigurasi Firebase sungguhan dan tidak memiliki resource live. Project ini biasanya diakses melalui codelab atau tutorial lainnya.

Project ID untuk project demo memiliki awalan demo-.

Jika menggunakan project Firebase demo, aplikasi dan kode Anda hanya berinteraksi dengan emulator. Jika aplikasi Anda mencoba berinteraksi dengan resource yang tidak dijalankan dengan emulator, kode tersebut akan gagal.

Jika memungkinkan, sebaiknya gunakan project demo. Manfaatnya meliputi:

  • Penyiapan yang lebih mudah karena Anda dapat menjalankan emulator tanpa perlu membuat project Firebase
  • Keamanan yang lebih tangguh karena jika kode Anda tidak sengaja memanggil resource yang tidak diemulasi (produksi), tidak akan terjadi perubahan data, penggunaan, dan penagihan
  • Dukungan offline yang lebih baik karena Anda tidak perlu mengakses internet untuk mendownload konfigurasi SDK.

Melengkapi aplikasi untuk berkomunikasi dengan emulator

Android, platform Apple, dan Web SDK

Siapkan konfigurasi dalam aplikasi atau class pengujian untuk berinteraksi dengan Cloud Firestore seperti berikut.

Android
        // 10.0.2.2 is the special IP address to connect to the 'localhost' of
        // the host computer from an Android emulator.
        FirebaseFirestore firestore = FirebaseFirestore.getInstance();
        firestore.useEmulator("10.0.2.2", 8080);

        FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
                .setPersistenceEnabled(false)
                .build();
        firestore.setFirestoreSettings(settings);
EmulatorSuite.java
Swift
let settings = Firestore.firestore().settings
settings.host = "localhost:8080"
settings.isPersistenceEnabled = false
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Web version 9

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, 'localhost', 8080);
fs_emulator_connect.js

Web version 8

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("localhost", 8080);
}
emulator-suite.js

Tidak diperlukan penyiapan tambahan untuk menguji Cloud Functions yang dipicu oleh peristiwa Firestore menggunakan emulator. Saat emulator Firestore dan emulator Cloud Functions berjalan, keduanya otomatis bekerja sama.

Admin SDK

Firebase Admin SDK otomatis terhubung ke emulator Cloud Firestore saat variabel lingkungan FIRESTORE_EMULATOR_HOST ditetapkan:

export FIRESTORE_EMULATOR_HOST="localhost:8080"

Jika kode Anda berjalan di dalam emulator Cloud Functions, project ID dan konfigurasi lainnya akan otomatis ditetapkan saat memanggil initalizeApp.

Jika ingin kode Admin SDK terhubung ke emulator bersama yang berjalan di lingkungan lain, Anda harus menentukan project ID yang sama dengan yang ditetapkan menggunakan Firebase CLI. Anda dapat meneruskan project ID ke initializeApp secara langsung atau menetapkan variabel lingkungan GCLOUD_PROJECT.

Admin SDK Node.js
admin.initializeApp({ projectId: "your-project-id" });
Variabel Lingkungan
export GCLOUD_PROJECT="your-project-id"

Mengosongkan database di antara pengujian

Firestore produksi tidak menyediakan metode SDK platform untuk mengosongkan database, tetapi emulator Firestore memberikan endpoint REST secara khusus untuk tujuan ini, yang dapat dipanggil dari langkah penyiapan/pembongkaran framework pengujian, dari class pengujian, atau dari shell (misalnya, dengan curl) sebelum pengujian dimulai. Anda dapat menggunakan pendekatan ini sebagai alternatif dari sekadar menonaktifkan proses emulator.

Dalam metode yang sesuai, jalankan operasi HTTP DELETE, dengan menyediakan projectID Firebase Anda, misalnya firestore-emulator-example, ke endpoint berikut:

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Tentunya, kode Anda harus menunggu konfirmasi REST bahwa proses pengosongan selesai atau gagal.

Anda dapat melakukan operasi ini dari shell:

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Setelah menerapkan langkah seperti ini, Anda dapat mengurutkan pengujian dan memicu fungsi dengan kepastian bahwa data lama akan dihapus secara permanen di antara pengujian, dan Anda akan menggunakan konfigurasi pengujian dasar pengukuran yang baru.

Mengimpor dan mengekspor data

Emulator database dan emulator Cloud Storage dapat Anda gunakan untuk mengekspor data dari instance emulator yang sedang berjalan. Tentukan set data dasar pengukuran yang akan digunakan dalam pengujian unit atau alur kerja continuous integration, lalu ekspor untuk dibagikan kepada tim.

firebase emulators:export ./dir

Dalam pengujian, impor data dasar pengukuran saat memulai emulator.

firebase emulators:start --import=./dir

Anda dapat menginstruksikan emulator untuk mengekspor data saat penonaktifan, baik dengan menentukan jalur ekspor maupun hanya menggunakan jalur yang diteruskan ke flag --import.

firebase emulators:start --import=./dir --export-on-exit

Opsi impor dan ekspor data ini juga berfungsi dengan perintah firebase emulators:exec. Untuk mempelajari lebih lanjut, baca referensi perintah emulator.

Memvisualisasikan aktivitas Aturan Keamanan

Saat mengerjakan prototipe dan loop pengujian, Anda dapat menggunakan laporan dan alat visualisasi yang disediakan oleh Local Emulator Suite.

Menggunakan Pemantau Permintaan

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

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

Pemantau Permintaan Emulator Firestore yang menampilkan evaluasi Aturan Keamanan

Memvisualisasikan laporan evaluasi Aturan

Saat menambahkan Aturan Keamanan ke prototipe, Anda dapat mendebugnya dengan alat debug Local Emulator Suite.

Setelah menjalankan serangkaian pengujian, Anda dapat mengakses laporan cakupan pengujian yang menunjukkan evaluasi setiap aturan keamanan Anda.

Untuk mendapatkan laporan tersebut, buat kueri untuk endpoint yang terekspos pada emulator selagi emulator berjalan. Untuk versi yang mudah digunakan di browser, gunakan URL berikut:

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

Proses ini memecah aturan Anda menjadi beberapa ekspresi dan subekspresi, dan Anda dapat mengarahkan kursor ke ekspresi/subekspresi tersebut untuk melihat informasinya lebih lanjut, termasuk jumlah evaluasi dan nilai yang ditampilkan. Untuk versi JSON mentah data ini, sertakan URL berikut dalam kueri Anda:

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

Di sini, versi HTML laporan menyoroti evaluasi yang melempar error yang tidak terdefinisi dan bernilai null:

Perbedaan emulator Cloud Firestore dengan layanan produksi

Emulator Cloud Firestore berupaya mereplikasi perilaku layanan produksi secara akurat, tetapi ada beberapa batasan yang perlu diketahui.

Transaksi

Saat ini, emulator tidak menerapkan semua perilaku transaksi yang terlihat dalam layanan produksi. Saat Anda menguji fitur yang melibatkan beberapa penulisan serentak ke satu dokumen, emulator mungkin lambat untuk menyelesaikan permintaan tulis. Pada beberapa kasus, mungkin diperlukan hingga 30 detik hingga kunci dapat dilepas. Jika perlu, sesuaikan waktu tunggu pengujian.

Indeks

Emulator tidak melacak indeks gabungan, melainkan akan mengeksekusi kueri apa pun yang valid. Pastikan untuk menguji aplikasi Anda terhadap instance Cloud Firestore sungguhan untuk menentukan indeks yang akan diperlukan.

Batas

Emulator tidak menerapkan semua batasan yang diterapkan dalam layanan produksi. Misalnya, emulator dapat mengizinkan transaksi yang akan ditolak oleh layanan produksi karena terlalu besar. Pastikan Anda memahami batasan yang didokumentasikan dan mendesain aplikasi untuk menghindarinya secara proaktif.

Apa selanjutnya?