Local Emulator Suite のインストール、構成、統合

Firebase Local Emulator Suite は、1 回限りのプロトタイピング セッションから本番環境規模の継続的インテグレーションのワークフローまで、さまざまなプロトタイプ環境とテスト環境にインストールして構成することができます。

Local Emulator Suite のインストール

Emulator Suite をインストールする前に、以下が必要です。

  • Node.js バージョン 16.0 以降。
  • Java JDK バージョン 11 以降。

Emulator Suite をインストールするには:

  1. Firebase CLI をインストールします。Firebase CLI をまだインストールしていない場合は、インストールしてください。Emulator Suite を使用するには、CLI バージョン 8.14.0 以降が必要です。次のコマンドを使用して、インストールしたバージョンを確認できます。
    firebase --version
  2. まだ行っていない場合は、画面の指示に従って使用するサービスを指定し、現在の作業ディレクトリを Firebase プロジェクトとして初期化します。
    firebase init
  3. Emulator Suite を設定します。このコマンドにより構成ウィザードが起動します。目的のエミュレータを選択し、対応するエミュレータのバイナリ ファイルをダウンロードして、デフォルトが適切でない場合はエミュレータ ポートを設定します。
    firebase init emulators

エミュレータがインストールされると、Firebase CLI のバージョンを更新するまで、アップデートのチェックは行われず、追加の自動ダウンロードも行われません。

Emulator Suite の構成

必要に応じて、エミュレータのネットワーク ポートとセキュリティ ルール定義へのパスを firebase.json ファイルで構成できます。

  • firebase init emulators を実行するか、firebase.json を手動で編集して、エミュレータのポートを変更します。
  • firebase.json を手動で編集して、セキュリティ ルールの定義へのパスを変更します。

これらの設定を構成しない場合、エミュレータはデフォルトのポートでリッスンし、Cloud Firestore、Realtime Database、Cloud Storage for Firebase のエミュレータはオープンデータのセキュリティで実行されます。

コマンド 説明
init emulators エミュレータの初期化ウィザードを開始します。インストールするエミュレータを特定し、必要に応じてエミュレータのポート設定を指定します。init emulators は変更を加えません。デフォルトのままにすると、現在のエミュレータ構成が保持されます。

ポートの構成

各エミュレータは、希望するデフォルト値でマシン上の異なるポートにバインドされます。

エミュレータ デフォルト ポート
Authentication 9099
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

プロジェクト ID の構成

エミュレータの呼び出し方法によっては、異なる Firebase プロジェクト ID を使用して複数のエミュレータ インスタンスを実行したり、特定のプロジェクト ID に対して複数のエミュレータ インスタンスを実行したりできます。その場合、エミュレータ インスタンスは個別の環境で実行されます。

通常は、すべてのエミュレータ呼び出しで 1 つのプロジェクト ID を使用することをおすすめします。そうすると、Emulator Suite UI、さまざまなプロダクト エミュレータ、特定のエミュレータの実行中のすべてのインスタンスが、すべてのケースで正しく通信できます。

Local Emulator Suite は、環境内に複数のプロジェクト ID を検出すると警告が発生しますが、この動作は firebase.jsonsingleProjectMode キーを false に設定してオーバーライドできます。

プロジェクト ID の宣言の不一致に関しては、次の場所で確認できます。

  • コマンドラインのデフォルト プロジェクト。デフォルトでは、プロジェクト ID は firebase init または firebase use で選択されたプロジェクトから起動時に取得されます。プロジェクトのリストを表示して選択されているプロジェクトを確認するには、firebase projects:list を使用します。
  • ルールの単体テスト。 プロジェクト ID は、多くの場合、ルール単体テスト ライブラリのメソッド initializeTestEnvironment または initializeTestApp の呼び出しで指定されます。
  • コマンドラインの --project フラグ。Firebase CLI の --project フラグを渡すと、デフォルトのプロジェクトがオーバーライドされます。このフラグの値が単体テストとアプリ初期化におけるプロジェクト ID と一致していることを確認する必要があります。

また、Apple プラットフォームAndroidウェブのプロジェクトを構成するときに設定したプラットフォーム固有のプロジェクト ID の構成も確認してください。

セキュリティ ルールの構成

エミュレータは、firebase.json 内に指定されている databasefirestorestorage の構成キーからセキュリティ ルールの構成を取得します。

{
  // 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"
    }
  }
}

Java オプションの指定

Realtime Database エミュレータ、Cloud Firestore エミュレータ、Cloud Storage for Firebase エミュレータの一部は Java をベースにしており、環境変数 JAVA_TOOL_OPTIONS を通じて JVM フラグを指定することによってカスタマイズできます。

たとえば、Java ヒープスペースに関連するエラーが発生する場合は、Java ヒープの最大サイズを 4 GB に増やすことができます。

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

複数のフラグを指定するには、JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g" のように引用符で囲み、スペースで区切ります。このフラグは、エミュレータの Java ベースのコンポーネントにのみ影響し、Firebase CLI の他の部分(Emulator Suite UI など)には影響しません。

エミュレータの起動

エミュレータは手動で終了するまで実行するようにするか、指定したテスト スクリプトの期間に実行させて自動でシャットダウンさせることができます。

コマンド 説明
emulators:start firebase.json で構成された Firebase プロダクトのエミュレータを起動します。エミュレータのプロセスは、明示的に停止されるまで実行を続けます。emulators:start を呼び出すと、~/.cache/firebase/emulators/ にエミュレータがダウンロードされます(まだインストールされていない場合)。
フラグ 説明
--only 省略可。起動するエミュレータを制限します。エミュレータ名のカンマ区切りのリストを指定し、「auth」、「database」、「firestore」、「functions」、「hosting」、「pubsub」のいずれかまたは複数を指定します。
--inspect-functions debug_port 省略可。Cloud Functions エミュレータで使用して、指定したポート(引数を省略した場合はデフォルトのポート 9229)で関数のブレークポイントのデバッグを有効にします。このフラグを指定すると、Cloud Functions エミュレータは特別なシリアル化された実行モードに切り替わり、関数は単一のプロセスで順次(FIFO)実行されます。これにより、関数のデバッグが簡単になりますが、動作はクラウド内で並列実行される関数のマルチプロセスとは異なります。
--export-on-exit= 省略可。Authentication、Cloud Firestore、Realtime Database、Cloud Storage for Firebase のエミュレータで使用します。emulators:export コマンドの説明に従って、シャットダウンが発生したときにディレクトリにデータをエクスポートするようにエミュレータに指示します。エクスポート ディレクトリは firebase emulators:start --export-on-exit=./saved-data フラグで指定できます。--import を使用する場合、エクスポート パスはデフォルトで同じになります(例: firebase emulators:start --import=./data-path --export-on-exit)。最後に、必要に応じて --import フラグと --export-on-exit フラグに別のディレクトリ パスを渡します。
--import=import_directory 省略可。Authentication、Cloud Firestore、Realtime Database、Cloud Storage for Firebase のエミュレータで使用します。--export-on-exit スタートアップ オプションまたは emulators:export コマンドを使用して、保存したデータを実行中の Authentication、Cloud Firestore、Realtime Database、Cloud Storage for Firebase のエミュレータ インスタンスにインポートします。現在エミュレータのメモリにあるデータは上書きされます。
emulators:exec scriptpath firebase.json で構成された Firebase プロダクトのエミュレータを起動した後、scriptpath でスクリプトを実行します。スクリプトの実行が終了すると、エミュレータ プロセスは自動的に停止します。
フラグ 説明
--only 省略可。起動するエミュレータを制限します。エミュレータ名のカンマ区切りのリストを指定し、「firestore」、「database」、「functions」、「hosting」、「pubsub」のいずれかまたは複数を指定します。
--inspect-functions debug_port 省略可。Cloud Functions エミュレータで使用して、指定したポート(引数を省略した場合はデフォルトのポート 9229)で関数のブレークポイントのデバッグを有効にします。このフラグを指定すると、Cloud Functions エミュレータは特別なシリアル化された実行モードに切り替わり、関数は単一のプロセスで順次(FIFO)実行されます。これにより、関数のデバッグが簡単になりますが、動作はクラウド内で並列実行される関数のマルチプロセスとは異なります。
--export-on-exit= 省略可。Authentication、Cloud Firestore、Realtime Database、Cloud Storage for Firebase のエミュレータで使用します。emulators:export コマンドの説明に従って、シャットダウンが発生したときにディレクトリにデータをエクスポートするようにエミュレータに指示します。エクスポート ディレクトリは firebase emulators:start --export-on-exit=./saved-data フラグで指定できます。--import を使用する場合、エクスポート パスはデフォルトで同じになります(例: firebase emulators:start --import=./data-path --export-on-exit)。最後に、必要に応じて --import フラグと --export-on-exit フラグに別のディレクトリ パスを渡します。
--import=import_directory 省略可。Authentication、Cloud Firestore、Realtime Database、Cloud Storage for Firebase のエミュレータで使用します。--export-on-exit スタートアップ オプションまたは emulators:export コマンドを使用して、保存したデータを実行中の Authentication、Cloud Firestore、Realtime Database、Cloud Storage for Firebase のエミュレータ インスタンスにインポートします。現在エミュレータのメモリにあるデータは上書きされます。
--ui 省略可。実行中にエミュレータ UI を実行します。

firebase emulators:exec メソッドは通常、継続的インテグレーションのワークフローに適しています。

エミュレータ データのエクスポートとインポート

Authentication、Cloud Firestore、Realtime Database、Cloud Storage for Firebase のエミュレータからデータをエクスポートして、共有可能な共通のベースラインのデータセットとして使用できます。これらのデータセットは、上述のように --import フラグを使用してインポートできます。

emulators:export export_directory

Authentication、Cloud Firestore、Realtime Database、Cloud Storage for Firebase のエミュレータ。実行中の Cloud Firestore、Realtime Database、Cloud Storage for Firebase のエミュレータ インスタンスからデータをエクスポートします。指定された export_directory がまだ存在しない場合は作成されます。指定したディレクトリが存在する場合は、以前のエクスポート データを上書きするかどうかを確認するメッセージが表示されます。このプロンプトは、--force フラグを使用してスキップできます。エクスポート ディレクトリには、データのマニフェスト ファイル firebase-export-metadata.json が含まれています。

シャットダウン時に上述の --export-on-exit フラグを使用して、自動的にデータをエクスポートするようにエミュレータに指示できます。

CI システムとの統合

コンテナ化された Emulator Suite イメージの実行

一般的な CI 設定でのコンテナを使用した Emulator Suite のインストールと構成はシンプルです。

次の点にご注意ください。

  • JAR ファイルは ~/.cache/firebase/emulators/ にインストールされ、キャッシュされます。

    • ダウンロードが繰り返されないようにするには、このパスを CI キャッシュ構成に追加します。
  • リポジトリに firebase.json ファイルがない場合は、emulators:start コマンドまたは emulators:exec コマンドにコマンドライン引数を追加して、起動するエミュレータを指定する必要があります。例:
    --only functions,firestore

認証トークンを生成する(Hosting エミュレータのみ)

継続的インテグレーションのワークフローが Firebase Hosting に依存している場合は、firebase emulators:exec を実行するためにトークンを使用してログインする必要があります。他のエミュレータではログインする必要がありません。

トークンを生成するには、ローカル環境で firebase login:ci を実行します。これは CI システムからは実行しないでください。手順に沿って認証します。トークンはビルド全体で有効になるため、この手順はプロジェクトごとに 1 回だけ実行する必要があります。トークンはパスワードのように扱い、機密性を保持する必要があります。

CI 環境でビルド スクリプトで使用可能な環境変数を指定できる場合は、FIREBASE_TOKEN という名前の環境変数を作成し、値をアクセス トークンの文字列にします。Firebase CLI が自動的に FIREBASE_TOKEN 環境変数を取得し、エミュレータが正しく起動します。

最後の手段として、シンプルにビルド スクリプトにトークンを含めることができますが、信頼できない第三者がアクセスできないようにする必要があります。このハードコードされたアプローチでは、firebase emulators:exec コマンドに --token "YOUR_TOKEN_STRING_HERE" を追加できます。

Emulator Hub REST API を使用する

実行中のエミュレータのリストを取得する

現在実行中のエミュレータのリストを取得するには、エミュレータ ハブの /emulators エンドポイントに GET リクエストを送信します。

curl localhost:4400/emulators

結果として、実行中のすべてのエミュレータと、そのホストおよびポートの構成などのリストが含まれる JSON オブジェクトが返されます。

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

バックグラウンド関数のトリガーを有効または無効にする

場合によっては、ローカル関数のトリガーと拡張機能のトリガーを一時的に無効にする必要があります。たとえば、Cloud Functions エミュレータや Extentions エミュレータで実行されている onDelete 関数をトリガーすることなく、Cloud Firestore エミュレータのすべてのデータを削除する場合などです。

ローカル関数のトリガーを一時的に無効にするには、エミュレータ ハブの /functions/disableBackgroundTriggers エンドポイントに PUT リクエストを送信します。

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

結果として、現在の状態の詳細を示す JSON オブジェクトが返されます。

{
  "enabled": false
}

ローカル関数のトリガーを無効にした後でもう一度有効にするには、エミュレータ ハブの /functions/enableBackgroundTriggers エンドポイントに PUT リクエストを送信します。

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

結果として、現在の状態の詳細を示す JSON オブジェクトが返されます。

{
  "enabled": true
}

エミュレータと SDK の統合

このセクションの表は、クライアント SDK と Admin SDK でサポートされているエミュレータを示しています。「対応予定」は、エミュレータのサポートが計画されているものの、まだサポートされていないことを意味します。

クライアント SDK の対応状況

Android Apple プラットフォーム Web Firebase UI
Android
Firebase UI
iOS
Firebase UI
ウェブ
Realtime Database 19.4.0 7.2.0 8.0.0 6.4.0 対応予定 なし
Cloud Firestore 21.6.0 7.2.0 8.0.0 6.4.0 対応予定 なし
Authentication 20.0.0 7.0.0 8.0.0 7.0.0 対応予定 4.7.2
Cloud Storage for Firebase 20.0.0 8.0.0 8.4.0 7.0.0 11.0.0 なし
Cloud Functions 19.1.0 7.2.0 8.0.0 なし なし なし
Hosting なし なし なし なし なし なし
Extensions なし なし なし なし なし なし

Admin SDK の対応状況

Node Java Python Go
Realtime Database 8.6.0 6.10.0 2.18.0 対応予定
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 対応予定 対応予定 対応予定
Cloud Functions なし なし なし なし
Hosting なし なし なし なし
Extensions なし なし なし なし