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 8.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 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
UI Emulator Suite 4000
Cloud Functions 5001
Realtime Database 9000
Cloud Firestore 8080
Cloud Storage 9199
Firebase Hosting 5000
Pub/Sub 8085

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": {
    "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 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 UI Emulator Suite.

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 akan menyederhanakan proses debug fungsi, meskipun perilakunya berbeda dengan eksekusi fungsi secara multiproses dan paralel di cloud.
--export-on-exit= Opsional. Digunakan dengan emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage. 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. Digunakan dengan emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage. Mengimpor data yang disimpan menggunakan opsi memulai --export-on-exit atau perintah emulators:export ke instance emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage 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 akan menyederhanakan proses debug fungsi, meskipun perilakunya berbeda dengan eksekusi fungsi secara multiproses dan paralel di cloud.
--export-on-exit= Opsional. Digunakan dengan emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage. 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. Digunakan dengan emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage. Mengimpor data yang disimpan menggunakan opsi memulai --export-on-exit atau perintah emulators:export ke instance emulator Authentication, Cloud Firestore, Realtime Database, atau Cloud Storage 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 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. Mengekspor data dari instance emulator Cloud Firestore, Realtime Database, atau Cloud Storage 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 permintaan 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. Misalnya,
    --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.

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 Future
Cloud Storage 20.0.0 8.0.0 8.4.0 T/A T/A 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
Ekstensi 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 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
Ekstensi T/A T/A T/A T/A