Menginstal, mengonfigurasi, dan mengintegrasikan Local Emulator Suite

Firebase Local Emulator Suite dapat diinstal dan dikonfigurasikan untuk berbagai prototipe dan lingkungan pengujian, mulai dari sesi pembuatan prototipe satu kali hingga alur kerja continuous integration berskala produksi.

Menginstal Local Emulator Suite

Sebelum menginstal Emulator Suite, Anda memerlukan:

• Node.js versi 16.0 atau yang lebih baru.
• Java JDK versi 11 atau yang lebih baru.

Untuk menginstal Emulator Suite:

1. Instal Firebase CLI. Jika Anda belum menginstal Firebase CLI, lakukan sekarang. Anda memerlukan CLI versi 8.14.0 atau yang lebih baru untuk menggunakan Emulator Suite. Anda dapat memeriksa versi CLI yang terinstal menggunakan perintah berikut:

   firebase --version

2. Jika Anda belum melakukannya, lakukan inisialisasi direktori kerja saat ini sebagai project Firebase, dengan mengikuti petunjuk di layar untuk menentukan produk yang akan digunakan:

   firebase init

3. Siapkan Emulator Suite. Perintah ini akan memulai wizard konfigurasi sehingga Anda dapat memilih emulator yang diminati, mendownload file biner yang sesuai dengan emulator tersebut, dan menetapkan port emulator jika port default tidak sesuai.

   firebase init emulators

Setelah emulator diinstal, tidak akan ada pemeriksaan update dan download otomatis tambahan yang dilakukan sebelum Anda mengupdate versi Firebase CLI.

Mengonfigurasi Emulator Suite

Anda dapat secara opsional mengonfigurasi port jaringan emulator dan jalur ke definisi Aturan Keamanan di file firebase.json:

• Ubah port emulator dengan menjalankan firebase init emulators atau dengan mengedit firebase.json secara manual.
• Ubah jalur ke definisi Aturan Keamanan dengan mengedit firebase.json secara manual.

Jika Anda tidak mengonfigurasi setelan ini, emulator akan melakukan pemrosesan melalui port defaultnya, dan emulator Cloud Firestore, Realtime Database, serta Cloud Storage for Firebase akan dijalankan dengan keamanan data terbuka.

Perintah	Deskripsi
init emulators	Memulai wizard inisialisasi emulator. Mengidentifikasi emulator yang akan diinstal dan secara opsional menentukan setelan port emulator. init emulators bersifat nondestruktif. Jika Anda menerima setelan default, konfigurasi emulator saat ini tetap akan dipertahankan.

Konfigurasi port

Setiap emulator terikat ke port yang berbeda di mesin Anda dengan nilai default yang diinginkan.

Emulator	Port Default
Authentication	9099
App Hosting	5002
Emulator Suite UI	4000
Cloud Functions	5001
Eventarc	9299
Realtime Database	9000
Cloud Firestore	8080
Cloud Storage for Firebase	9199
Firebase Hosting	5000
Pub/Sub	8085

Konfigurasi Project ID

Bergantung pada cara Anda memanggil emulator, Anda dapat menjalankan beberapa instance emulator menggunakan project ID Firebase yang berbeda atau beberapa instance emulator untuk project ID tertentu. Dalam kasus seperti itu, instance emulator berjalan di lingkungan yang terpisah.

Umumnya, sebaiknya tetapkan satu project ID untuk semua pemanggilan emulator, sehingga Emulator Suite UI, emulator produk yang berbeda, dan semua instance emulator tertentu yang berjalan dapat berkomunikasi dengan benar dalam semua kasus.

Local Emulator Suite mengeluarkan peringatan saat mendeteksi beberapa project ID di lingkungan, meskipun Anda dapat mengganti perilaku ini dengan menetapkan kunci singleProjectMode ke false di firebase.json Anda.

Anda dapat memeriksa pernyataan project ID untuk ketidakcocokan di:

• Project default di command line. Secara default, project ID akan diambil saat project dimulai dari project yang dipilih dengan firebase init atau firebase use. Untuk melihat daftar project (dan melihat project mana yang dipilih), gunakan firebase projects:list.
• Pengujian unit aturan. Project ID sering ditentukan dalam panggilan ke metode library Pengujian Unit Aturan initializeTestEnvironment atau initializeTestApp.
• Flag command line --project. Meneruskan flag --project Firebase CLI akan menggantikan project default. Anda harus memastikan nilai flag sesuai dengan project ID dalam pengujian unit dan inisialisasi aplikasi.

Periksa juga konfigurasi project ID khusus platform yang telah Anda tetapkan saat mengonfigurasi project platform Apple, Android, dan web.

Konfigurasi Aturan Keamanan

Emulator akan mengambil konfigurasi Aturan Keamanan dari kunci konfigurasi database, firestore dan storage di firebase.json.

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore": {
    "rules": "firestore.rules"
  },
  "storage": {
    "rules": "storage.rules"
  }

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "singleProjectMode": false, // do not warn on detection of multiple project IDs
    "firestore": {
      "port": "8080"
    },
    "ui": {
      "enabled": true,      // Default is `true`
      "port": 4000          // If unspecified, see CLI log for selected port
    },
    "auth": {
      "port": "9099"
    },
    "pubsub": {
      "port": "8085"
    }
  }
}

Menentukan opsi Java

Emulator Realtime Database, emulator Cloud Firestore, dan bagian dari emulator Cloud Storage for Firebase didasarkan pada Java, yang dapat disesuaikan dengan flag JVM melalui variabel lingkungan JAVA_TOOL_OPTIONS.

Misalnya, jika mengalami error terkait ruang heap Java, Anda dapat meningkatkan ukuran heap Java maksimum menjadi 4 GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

Beberapa flag dapat ditentukan dalam tanda petik yang dipisahkan dengan spasi, seperti JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g". Flag ini hanya memengaruhi komponen emulator berbasis Java dan tidak berpengaruh pada bagian lain dari Firebase CLI, seperti Emulator Suite UI.

Memulai emulator

Anda dapat memulai emulator agar berjalan hingga dihentikan secara manual, atau agar berjalan sesuai durasi skrip pengujian yang ditentukan, lalu berhenti secara otomatis.

Perintah	Deskripsi
emulators:start	Memulai emulator untuk produk Firebase yang dikonfigurasi di firebase.json. Proses emulator akan terus berjalan hingga dihentikan secara eksplisit. Memanggil emulators:start akan mendownload emulator ke ~/.cache/firebase/emulators/ jika emulator belum terinstal. Flag Deskripsi --only Opsional. Membatasi emulator mana yang akan dimulai. Memberikan daftar nama emulator yang dipisahkan koma, yang menentukan satu atau beberapa 'auth', 'database', 'firestore', 'functions', 'hosting', atau 'pubsub'. --inspect-functions debug_port Opsional. Digunakan dengan emulator Cloud Functions untuk mengaktifkan proses debug titik henti sementara fungsi pada port yang ditentukan (atau port default 9229 jika argumen dihilangkan). Perlu diperhatikan bahwa saat flag ini diberikan, emulator Cloud Functions akan beralih ke mode eksekusi serial khusus. Dalam mode ini fungsi akan dijalankan dalam satu proses, secara berurutan (FIFO). Hal ini menyederhanakan proses debug fungsi, meskipun perilakunya berbeda dengan eksekusi fungsi secara multiproses dan paralel di cloud. --export-on-exit= Opsional. Gunakan dengan emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage for Firebase. Menginstruksikan emulator untuk mengekspor data ke suatu direktori saat terjadi penghentian, seperti yang dijelaskan untuk perintah emulators:export. Direktori ekspor dapat ditentukan dengan flag ini: firebase emulators:start --export-on-exit=./saved-data. Jika --import digunakan, jalur ekspor akan disetel ke default yang sama; misalnya: firebase emulators:start --import=./data-path --export-on-exit. Terakhir, jika diinginkan, teruskan jalur direktori yang berbeda ke flag --import dan --export-on-exit. --import=import_directory Opsional. Gunakan dengan emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage for Firebase. Impor data yang disimpan menggunakan opsi memulai --export-on-exit atau perintah emulators:export ke instance emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage for Firebase yang sedang berjalan. Setiap data yang saat ini ada dalam memori emulator akan ditimpa.
emulators:exec scriptpath	Menjalankan skrip di scriptpath setelah memulai emulator untuk produk Firebase yang dikonfigurasi di firebase.json. Proses emulator akan otomatis berhenti saat skrip selesai berjalan. Flag Deskripsi --only Opsional. Membatasi emulator mana yang akan dimulai. Memberikan daftar nama emulator yang dipisahkan koma, yang menentukan satu atau beberapa 'firestore', 'database', 'functions', 'hosting', atau 'pubsub'. --inspect-functions debug_port Opsional. Digunakan dengan emulator Cloud Functions untuk mengaktifkan proses debug titik henti sementara fungsi pada port yang ditentukan (atau port default 9229 jika argumen dihilangkan). Perlu diperhatikan bahwa saat flag ini diberikan, emulator Cloud Functions akan beralih ke mode eksekusi serial khusus. Dalam mode ini fungsi akan dijalankan dalam satu proses, secara berurutan (FIFO). Hal ini menyederhanakan proses debug fungsi, meskipun perilakunya berbeda dengan eksekusi fungsi secara multiproses dan paralel di cloud. --export-on-exit= Opsional. Gunakan dengan emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage for Firebase. Menginstruksikan emulator untuk mengekspor data ke suatu direktori saat terjadi penghentian, seperti yang dijelaskan untuk perintah emulators:export. Direktori ekspor dapat ditentukan dengan flag ini: firebase emulators:start --export-on-exit=./saved-data. Jika --import digunakan, jalur ekspor akan disetel ke default yang sama; misalnya: firebase emulators:start --import=./data-path --export-on-exit. Terakhir, jika diinginkan, teruskan jalur direktori yang berbeda ke flag --import dan --export-on-exit. --import=import_directory Opsional. Gunakan dengan emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage for Firebase. Impor data yang disimpan menggunakan opsi memulai --export-on-exit atau perintah emulators:export ke instance emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage for Firebase yang sedang berjalan. Setiap data yang saat ini ada dalam memori emulator akan ditimpa. --ui Opsional. Menjalankan UI Emulator selama eksekusi.

Metode firebase emulators:exec umumnya lebih sesuai untuk alur kerja continuous integration.

Mengekspor dan mengimpor data emulator

Anda dapat mengekspor data dari emulator Authentication, Cloud Firestore, Realtime Database, dan Cloud Storage for Firebase untuk digunakan sebagai set data dasar pengukuran umum yang dapat dibagikan. Set data ini dapat diimpor menggunakan flag --import, seperti yang dijelaskan di atas.

emulators:export export_directory

Emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage for Firebase. Mengekspor data dari instance emulator Cloud Firestore, Realtime Database, atau Cloud Storage for Firebase yang sedang berjalan. export_directory yang ditentukan akan dibuat jika belum ada. Jika direktori yang ditentukan sudah ada, Anda akan diminta untuk mengonfirmasi bahwa data ekspor sebelumnya harus ditimpa. Anda dapat melewati perintah ini menggunakan flag --force. Direktori ekspor berisi file manifes data, firebase-export-metadata.json. Anda dapat menginstruksikan emulator untuk mengekspor data secara otomatis saat berhenti menggunakan flag --export-on-exit yang dijelaskan di atas.

Melakukan integrasi dengan sistem CI Anda

Menjalankan image Emulator Suite dalam container

Penginstalan dan konfigurasi Emulator Suite dengan container dalam penyiapan CI biasa sangat mudah dilakukan.

Ada beberapa hal yang perlu diperhatikan:

• File JAR diinstal dan di-cache di ~/.cache/firebase/emulators/.

  • Anda dapat menambahkan jalur ini ke konfigurasi cache CI Anda untuk menghindari download berulang.

• Jika tidak memiliki file firebase.json di repositori, Anda harus menambahkan argumen command line ke perintah emulators:start atau emulators:exec untuk menentukan emulator yang harus dimulai. Contoh,
  --only functions,firestore.

Membuat token autentikasi (khusus emulator Hosting)

Jika alur kerja continuous integration Anda mengandalkan Firebase Hosting, Anda harus login menggunakan token agar dapat menjalankan firebase emulators:exec. Emulator lain tidak memerlukan login.

Catatan: Jika Anda telah mengonfigurasi hosting di firebase.json tetapi tidak membutuhkannya di penyiapan pengujian CI, gunakan flag --only pada emulators:start atau emulators:exec untuk hanya menyertakan emulator yang Anda butuhkan.

Untuk membuat token, jalankan firebase login:ci di lingkungan lokal Anda. Hal ini tidak boleh dilakukan dari sistem CI. Ikuti petunjuk untuk melakukan autentikasi. Anda hanya perlu melakukan langkah ini sekali per project, karena token akan bersifat valid di seluruh build. Token harus diperlakukan seperti sandi. Pastikan token dirahasiakan.

Jika lingkungan CI memungkinkan Anda menentukan variabel lingkungan yang dapat digunakan dalam skrip build, cukup buat variabel lingkungan bernama FIREBASE_TOKEN, dengan nilai berupa string token akses. Firebase CLI akan otomatis mengambil variabel lingkungan FIREBASE_TOKEN dan emulator akan dimulai dengan benar.

Sebagai upaya terakhir, Anda cukup menyertakan token dalam skrip build, tetapi pastikan pihak yang tidak tepercaya tidak dapat mengaksesnya. Untuk pendekatan hard code ini, Anda dapat menambahkan --token "YOUR_TOKEN_STRING_HERE" ke perintah firebase emulators:exec.

Menggunakan Emulator Hub REST API

Mencantumkan emulator yang sedang berjalan

Untuk mencantumkan emulator yang sedang berjalan, kirim permintaan GET ke endpoint /emulators Emulator Hub.

curl localhost:4400/emulators

Hasilnya akan berupa objek JSON yang mencantumkan semua emulator yang sedang berjalan dan konfigurasi host/port-nya, misalnya:

{
  "hub":{
    "name": "hub",
    "host": "localhost",
    "port": 4400
  },
  "functions": {
    "name": "functions",
    "host": "localhost",
    "port": 5001
  }
  "firestore": {
    "name": "firestore",
    "host": "localhost",
    "port": 8080
  }
}

Mengaktifkan/Menonaktifkan Pemicu Fungsi Latar Belakang

Dalam beberapa situasi, Anda perlu menonaktifkan fungsi lokal dan pemicu ekstensi untuk sementara. Misalnya, Anda mungkin ingin menghapus semua data di emulator Cloud Firestore tanpa memicu fungsi onDelete apa pun yang sedang berjalan di emulator Cloud Functions atau Extensions.

Untuk menonaktifkan pemicu fungsi lokal untuk sementara, kirim permintaan PUT ke endpoint /functions/disableBackgroundTriggers Emulator Hub.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

Hasilnya akan berupa objek JSON yang memerinci status saat ini.

{
  "enabled": false
}

Untuk mengaktifkan pemicu fungsi lokal setelah dinonaktifkan, kirim permintaan PUT ke endpoint /functions/enableBackgroundTriggers Emulator Hub.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

Hasilnya akan berupa objek JSON yang memerinci status saat ini.

{
  "enabled": true
}

Integrasi Emulator SDK

Tabel di bagian ini menunjukkan emulator yang didukung oleh SDK klien dan Admin SDK. Future berarti dukungan emulator sudah direncanakan tetapi belum tersedia.

Ketersediaan SDK klien

	Android	Platform Apple	Web	UI Firebase Android	UI Firebase iOS	UI Firebase Web
Realtime Database	19.4.0	7.2.0	8.0.0	6.4.0	Future	T/A
Cloud Firestore	21.6.0	7.2.0	8.0.0	6.4.0	Future	T/A
Authentication	20.0.0	7.0.0	8.0.0	7.0.0	Future	4.7.2
Cloud Storage for Firebase	20.0.0	8.0.0	8.4.0	7.0.0	11.0.0	T/A
Cloud Functions	19.1.0	7.2.0	8.0.0	T/A	T/A	T/A
Hosting	T/A	T/A	T/A	T/A	T/A	T/A
Extensions	T/A	T/A	T/A	T/A	T/A	T/A

Ketersediaan Admin SDK

	Node	Java	Python	Go
Realtime Database	8.6.0	6.10.0	2.18.0	Future
Cloud Firestore	8.0.0	6.10.0	3.0.0	1.0.0
Authentication	9.3.0	7.2.0	5.0.0	4.2.0
Cloud Storage for Firebase	9.8.0	Future	Future	Future
Cloud Functions	T/A	T/A	T/A	T/A
Hosting	T/A	T/A	T/A	T/A
Extensions	T/A	T/A	T/A	T/A