Menguji Mode Datastore menggunakan emulator Firestore

Google Cloud CLI menyediakan emulator dalam memori lokal untuk Firestore yang dapat Anda gunakan untuk menguji aplikasi Firestore dalam mode Datastore. Anda dapat menggunakan emulator dengan semua library klien mode Datastore. Anda hanya boleh menggunakan emulator untuk pengujian lokal.

Gunakan gcloud emulators firestore dengan --database-mode=datastore-mode untuk menguji perilaku Firestore dalam mode Datastore.

Jangan gunakan emulator untuk deployment produksi. Karena emulator hanya menyimpan data dalam memori, emulator tidak mempertahankan data di seluruh proses.

Menginstal emulator

Untuk menginstal emulator Firestore, instal dan update gcloud CLI:

  1. Instal gcloud CLI.

  2. Update instalasi gcloud CLI untuk mendapatkan fitur terbaru:

    gcloud components update

Menjalankan emulator

  1. Jalankan perintah berikut untuk memulai emulator:

    gcloud emulators firestore start --database-mode=datastore-mode

    Emulator akan mencetak host dan nomor port tempat emulator berjalan.

    Secara default, emulator mencoba menggunakan 127.0.0.1:8080. Untuk mengikat emulator ke host dan port tertentu, gunakan flag --host-port opsional, dengan mengganti HOST dan PORT:

    gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORT

  2. Gunakan pintasan keyboard Control + C untuk menghentikan emulator.

Menghubungkan ke emulator

Untuk menghubungkan library klien dan aplikasi ke emulator, tetapkan variabel lingkungan DATASTORE_EMULATOR_HOST. Jika variabel lingkungan ini ditetapkan, library klien akan otomatis terhubung ke emulator.

export DATASTORE_EMULATOR_HOST="HOST:PORT"

Mengimpor entity ke emulator

Fitur impor emulator memungkinkan Anda memuat entity dari sekumpulan file ekspor entity ke emulator. File ekspor entity dapat berasal dari ekspor database mode Datastore atau dari instance emulator.

Anda dapat mengimpor entity ke emulator dengan dua cara. Cara pertama adalah menambahkan flag import-data ke perintah mulai emulator. Metode kedua adalah mengirim permintaan impor POST ke emulator. Anda dapat menggunakan curl atau alat serupa. Lihat contoh berikut.

Protokol

curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:import \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE", "export_directory":"EXPORT_DIRECTORY"}'
Ubah localhost:8080 jika emulator menggunakan port yang berbeda.

Flag CLI

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY

dengan:

  • [PROJECT_ID] adalah ID project Anda.

  • [DATABASE] adalah jalur database. Misalnya, project dengan database default akan terlihat seperti berikut:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] adalah jalur ke file overall_export_metadata dari file ekspor entity Anda. Contoh:

    {"export_directory":"/home/user/myexports/2024-03-26T19:39:33_443/2024-03-26T19:39:33_443.overall_export_metadata"}

Mengekspor entity di emulator

Fitur ekspor emulator memungkinkan Anda menyimpan entity di emulator ke dalam sekumpulan file ekspor entity. Kemudian, Anda dapat menggunakan operasi impor untuk memuat entity dalam file ekspor entity ke database mode Datastore atau ke instance emulator.

Anda dapat mengekspor entity dari emulator dengan dua cara. Cara pertama adalah menambahkan flag export-on-exit ke perintah mulai emulator. Metode kedua adalah mengirim permintaan ekspor POST ke emulator. Anda dapat menggunakan curl atau alat serupa. Lihat contoh berikut.

Protokol

curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:export \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE_PATH", "export_directory":"EXPORT_DIRECTORY"}'
Ubah localhost:8080 jika emulator menggunakan port yang berbeda.

Flag CLI

gcloud emulators firestore start --database-mode=datastore-mode --export-on-exit=EXPORT_DIRECTORY

dengan:

  • [PROJECT_ID] adalah ID project Anda.

  • [DATABASE_PATH] adalah jalur database. Misalnya, project dengan database default akan terlihat seperti berikut:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] menentukan direktori tempat emulator menyimpan file ekspor entity. Direktori ini tidak boleh berisi sekumpulan file ekspor entity. Contoh:

    {"export_directory":"/home/user/myexports/2024-03-26/"}

Mempertahankan data di emulator

Secara default, emulator Firestore tidak mempertahankan data ke disk. Untuk mempertahankan data emulator, jalankan perintah berikut untuk menggunakan flag impor dan ekspor guna memuat dan menyimpan data di seluruh instance emulator:

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY --export-on-exit=EXPORT_DIRECTORY

Mereset data emulator

Emulator Firestore menyertakan endpoint REST untuk mereset semua data di emulator. Anda dapat menggunakan endpoint ini untuk menghapus data di antara pengujian tanpa mematikan emulator.

Untuk mereset semua data di emulator, lakukan operasi POST HTTP terhadap endpoint berikut, dengan mengganti HOST dan PORT dengan host dan port yang Anda pilih serta mengganti PROJECT_ID dengan project ID Anda sendiri:

http://HOST:PORT/reset

Sesuaikan host dan port jika emulator tidak menggunakan 127.0.0.1:8080. Kode Anda harus menunggu konfirmasi REST bahwa proses reset selesai atau gagal.

Anda dapat melakukan operasi ini dari shell menggunakan curl:

$ curl -X POST "http://HOST:PORT/reset"

Perbedaan emulator dengan produksi

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

Konkurensi dan konsistensi

Emulator hanya mendukung konkurensi pesimistis dan konsistensi kuat. Emulator tidak mendukung setelan konkurensi optimistis dan konsistensi eventual.

Transaksi

Emulator tidak mencoba meniru perilaku transaksi yang terlihat dalam produksi. Emulator menggunakan pendekatan penguncian sederhana dan tidak mencoba mencerminkan berbagai mode konkurensi yang ditawarkan di lingkungan produksi.

Saat Anda menguji fitur yang melibatkan beberapa penulisan serentak ke satu dokumen, emulator mungkin lambat untuk menyelesaikan permintaan tulis. Mungkin perlu waktu hingga 30 detik agar emulator dapat melepaskan kunci. Jika Anda perlu menyesuaikan interval waktu tunggu pengujian, lakukan hal tersebut.

Emulator juga tidak mencoba meniru semua batasan produksi, seperti waktu tunggu & batasan ukuran, yang melibatkan transaksi. Jika Anda menguji fitur yang bergantung pada batasan produksi ini, sebaiknya gunakan lingkungan produksi, bukan emulator.

Indeks

Secara default, emulator tidak melacak indeks gabungan, melainkan mengeksekusi kueri apa pun yang valid.

Untuk menguji apakah persyaratan indeks gabungan terpenuhi, mulai emulator dengan flag --require-indexes dan --index-file. Saat Anda memulai emulator dengan flag ini, emulator akan memeriksa dan menolak kueri yang memerlukan indeks gabungan yang tidak ditentukan dalam file indeks yang ditentukan.

gcloud emulators firestore start --database-mode=datastore-mode --require-indexes --index-file=./index.yaml

Lihat Mengonfigurasi Indeks Datastore dengan index.yaml untuk mengetahui informasi selengkapnya tentang format index-file.

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.

Langkah berikutnya