Firebase を使用して AI 搭載アプリを構築して実行する方法のデモを、2024 年の Demo Day でご覧ください。ぜひご覧ください。

Cloud Firestore セキュリティルールをテストする

アプリを構築する過程で Cloud Firestore データベースへのアクセスをロックダウンすることが必要な場合もありますが、リリースする前には、より詳細な Cloud Firestore Security Rules が必要になります。Cloud Firestore エミュレータを使用すると、アプリの一般的な機能と動作のプロトタイピングとテストに加えて、Cloud Firestore Security Rules の動作チェックを行う単体テストを作成できます。

クイックスタート

簡単なルールを使った基本的なテストケースについては、クイックスタートサンプルをお試しください。

Cloud Firestore Security Rules について理解する

モバイルクライアントライブラリやウェブクライアントライブラリを使用する場合は、サーバーレスの認証、認可、データ検証を行うために Firebase Authentication と Cloud Firestore Security Rules を実装します。

Cloud Firestore Security Rules には次の 2 つが含まれています。

データベース内のドキュメントを識別する match ステートメント
それらのドキュメントへのアクセスを制御する allow 式

Firebase Authentication はユーザーの認証情報を検証し、ユーザーベースとロールベースのアクセスシステムの基盤を提供します。

Cloud Firestore のモバイルクライアントライブラリまたはウェブクライアントライブラリから送られたすべてのデータベースリクエストは、データの読み取りまたは書き込みの前に、セキュリティルールと照合して評価されます。指定されたドキュメントパスのいずれかへのアクセスがルールによって拒否されると、リクエスト全体が失敗します。

Cloud Firestore Security Rules の詳細については、Cloud Firestore Security Rules を使ってみるをご覧ください。

エミュレータをインストールする

Cloud Firestore エミュレータをインストールするには、Firebase CLI を使用して次のコマンドを実行します。

firebase setup:emulators:firestore

エミュレータを実行する

まず、作業ディレクトリで Firebase プロジェクトを初期化します。これは、Firebase CLI を使用するときの一般的な最初のステップです。

firebase init

次のコマンドを使用してエミュレータを起動します。エミュレータは、プロセスを終了するまで実行されます。

firebase emulators:start --only firestore

多くの場合、エミュレータを起動し、テストスイートを実行して、テストの実行後にエミュレータをシャットダウンします。これは emulators:exec コマンドで簡単に実施できます。

firebase emulators:exec --only firestore "./my-test-script.sh"

エミュレータが起動すると、デフォルトポート（8080）での実行が試行されます。デフォルトポート以外のエミュレータポートで実行するには、firebase.json ファイルの "emulators" セクションを変更します。

{
  // ...
  "emulators": {
    "firestore": {
      "port": "YOUR_PORT"
    }
  }
}

エミュレータを実行する前に

エミュレータを使用する前に、次の点に注意してください。

エミュレータは最初に firebase.json ファイルの firestore.rules フィールドで指定されたルールを読み込みます。Cloud Firestore Security Rules が含まれているローカルファイルの名前をこのフラグに指定すると、そのセキュリティルールがすべてのプロジェクトに適用されます。以下で説明するとおり、ローカルファイルパスを指定しない場合、または loadFirestoreRules メソッドを使用しない場合、エミュレータはすべてのプロジェクトをオープンルールが適用されるものとして扱います。
ほとんどの Firebase SDK はエミュレータで直接動作しますが、セキュリティルールで auth の擬似的再現をサポートしているのは @firebase/rules-unit-testing ライブラリのみです。したがって、このライブラリでは単体テストがはるかに簡単になります。また、このライブラリは以下にリストされているエミュレータ固有の機能（すべてのデータのクリアなど）もサポートしています。
エミュレータは、クライアント SDK から提供される本番環境の Firebase Auth トークンも受け入れ、それに応じてルールを評価します。そのため、統合テストと手動テストでアプリケーションをエミュレータに直接接続できます。

ローカル単体テストを実行する

v9 JavaScript SDK を使用してローカル単体テストを実行する

Firebase は、バージョン 9 の JavaScript SDK とバージョン 8 の SDK の両方を備えた、セキュリティルールの単体テストライブラリを配布しています。これらのライブラリの API は大きく異なります。v9 テストライブラリの使用をおすすめします。v9 テストライブラリを使用すると、エミュレータへの接続がより効率化され、必要な設定も少なくて済みます。これにより、本番環境リソースが誤って使用されることを回避できます。下位互換性のために、引き続き v8 テストライブラリをご利用いただけます。

v9 SDK の一般的なテストメソッドとユーティリティ関数
v9 SDK のエミュレータ固有のテストメソッド

@firebase/rules-unit-testing モジュールを使用して、ローカルで動作するエミュレータを操作します。タイムアウトまたは ECONNREFUSED エラーが発生する場合は、エミュレータが実行されていることを確認してください。

async/await の表記法を使用できるようにするため、新しいバージョンの Node.js を使用することを強くおすすめします。テスト対象となる可能性のある動作のほとんどには非同期関数があります。また、テストモジュールは Promise ベースのコードで動作するように設計されています。

v9 ルールの単体テスト用ライブラリはエミュレータを常に認識し、本番環境のリソースに接続することはありません。

ライブラリをインポートするには、v9 モジュラーインポートステートメントを使用します。次に例を示します。

import {
  assertFails,
  assertSucceeds,
  initializeTestEnvironment
} from "@firebase/rules-unit-testing"

// Use `const { … } = require("@firebase/rules-unit-testing")` if imports are not supported
// Or we suggest `const testing = require("@firebase/rules-unit-testing")` if necessary.

インポートしたら単体テストを実装します。実装には次の作業が含まれます。

initializeTestEnvironment を呼び出して、RulesTestEnvironment を作成して構成します。
ルールを一時的にバイパスできる便利なメソッド RulesTestEnvironment.withSecurityRulesDisabled を使用して、ルールをトリガーせずにテストデータをセットアップします。
RulesTestEnvironment.cleanup() や RulesTestEnvironment.clearFirestore() など、テストデータと環境をクリーンアップするための呼び出しを使用して、テストスイートとテストごとの前後のフックをセットアップします。
RulesTestEnvironment.authenticatedContext と RulesTestEnvironment.unauthenticatedContext を使用して、認証状態を模倣するテストケースを実装します。

一般的なメソッドとユーティリティ関数

v9 SDK のエミュレータ固有のテストメソッドもご覧ください。

initializeTestEnvironment() => RulesTestEnvironment

この関数は、ルールの単体テストのテスト環境を初期化します。テストのセットアップを行うには、まずこの関数を呼び出します。これが正常に実行されるには、エミュレータが実行されている必要があります。

この関数は、TestEnvironmentConfig を定義するオプションのオブジェクトを受け入れます。このオブジェクトはプロジェクト ID とエミュレータ構成設定で構成されます。

let testEnv = await initializeTestEnvironment({
  projectId: "demo-project-1234",
  firestore: {
    rules: fs.readFileSync("firestore.rules", "utf8"),
  },
});

注: エミュレータは 1 回の実行において、テスト呼び出し間でデータを保持します。このデータ保持により、結果に影響することがあります。テストの実行後、次の実行の前にデータを消去するには、テストの合間で該当するエミュレータのデータ消去メソッド（clearFirestoreData など）を呼び出します。

RulesTestEnvironment.authenticatedContext({ user_id: string, tokenOptions?: TokenOptions }) => RulesTestContext

このメソッドは RulesTestContext を作成します。これは、認証された Authentication ユーザーと同様に動作します。返されたコンテキストを介して作成されたリクエストには、疑似の Authentication トークンが添付されます。必要に応じて、Authentication トークンペイロードのカスタムのクレームまたはオーバーライドを定義するオブジェクトを渡してください。

テストで返されたテストコンテキストオブジェクトを使用して、initializeTestEnvironment で構成されたものも含め、構成されたエミュレータインスタンスにアクセスします。

// Assuming a Firestore app and the Firestore emulator for this example
import { setDoc } from "firebase/firestore";

const alice = testEnv.authenticatedContext("alice", { … });
// Use the Firestore instance associated with this context
await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

RulesTestEnvironment.unauthenticatedContext() => RulesTestContext

このメソッドは RulesTestContext を作成します。これは、Authentication を介してログインしていないクライアントのように動作します。返されたコンテキストを介して作成されたリクエストには、Firebase Auth トークンが添付されません。

// Assuming a Cloud Storage app and the Storage emulator for this example
import { getStorage, ref, deleteObject } from "firebase/storage";

const alice = testEnv.unauthenticatedContext();

// Use the Cloud Storage instance associated with this context
const desertRef = ref(alice.storage(), 'images/desert.jpg');
await assertSucceeds(deleteObject(desertRef));

RulesTestEnvironment.withSecurityRulesDisabled()

セキュリティルールが無効になっているかのように動作するコンテキストで、テストセットアップ関数を実行します。

このメソッドはコールバック関数を受け取ります。このコールバック関数は Security-Rules-bypassing コンテキストを受け取って Promise を返します。Promise が解決または拒否されると、コンテキストは破棄されます。

RulesTestEnvironment.cleanup()

このメソッドは、テスト環境で作成されたすべての RulesTestContexts を破棄し、それらの元となっているリソースをクリーンアップします。これにより、クリーンな終了が可能になります。

このメソッドでは、エミュレータの状態は一切変更されません。複数のテストの合間にデータをリセットするには、アプリケーションエミュレータ固有のデータ消去メソッドを使用してください。

assertSucceeds(pr: Promise<any>)) => Promise<any>

これはテストケースのユーティリティ関数です。

この関数は、エミュレータオペレーションをラップする指定された Promise が、セキュリティルール違反なしで解決されることをアサートします。

await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

assertFails(pr: Promise<any>)) => Promise<any>

これはテストケースのユーティリティ関数です。

この関数は、エミュレータオペレーションをラップする指定された Promise が、セキュリティルール違反により拒否されることをアサートします。

await assertFails(setDoc(alice.firestore(), '/users/bob'), { ... });

エミュレータ固有のメソッド

v9 SDK の一般的なテストメソッドとユーティリティ関数もご覧ください。

RulesTestEnvironment.clearFirestore() => Promise<void>

このメソッドは、Firestore エミュレータ用に構成された projectId に属する Firestore データベースのデータをクリアします。

RulesTestContext.firestore(settings?: Firestore.FirestoreSettings) => Firestore;

このメソッドは、このテストのコンテキストの Firestore インスタンスを取得します。返された Firebase JS Client SDK インスタンスは、クライアント SDK API（v9 モジュラーまたは v9 互換）で使用できます。

ルール評価を可視化する

Cloud Firestore エミュレータを使用すると、Emulator Suite UI でクライアントリクエストを可視化できます。たとえば、Firebase セキュリティルールの評価トレースを行うことができます。

[Firestore] > [Requests] タブを開くと、各リクエストの詳細な評価シーケンスが表示されます。

セキュリティルールの評価を示す Firestore エミュレータのリクエストモニタリング

テストレポートを生成する

一連のテストを実行した後、それぞれのセキュリティルールの評価を示したテストカバレッジレポートにアクセスできます。

レポートを取得するには、エミュレータの実行中に公開されたエンドポイントに対してクエリを実行します。ブラウザでの表示に適したバージョンを参照するには、次の URL を使用します。

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

これによりルールが式やサブ式に分割されます。それぞれの式の上にマウスカーソルを重ねて、評価回数や返された値などの詳細情報を確認できます。このデータの未加工の JSON バージョンを取得するには、クエリに次の URL を含めます。

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

エミュレータと本番環境の違い

Cloud Firestore プロジェクトを明示的に作成する必要はありません。エミュレータがアクセスされるインスタンスを自動的に作成します。
Cloud Firestore エミュレータは、通常の Firebase Authentication フローでは動作しません。そこで、Firebase Test SDK の中には auth フィールドを受け取る initializeTestApp() メソッドが rules-unit-testing ライブラリに用意されています。このメソッドを使用して作成された Firebase ハンドルは、どのようなエンティティを指定しても正常に認証されたかのように動作します。null を渡すと、認証されていないユーザーとして動作します（たとえば auth != null ルールは失敗します）。

既知の問題のトラブルシューティング

Cloud Firestore エミュレータを使用する際には、次のような既知の問題が発生する可能性があります。発生する異常な動作をトラブルシューティングするには、以下のガイダンスに従ってください。これらの注記はセキュリティルールの単体テストライブラリを考慮して記述されていますが、一般的なアプローチはすべての Firebase SDK に適用されます。

テスト動作に一貫性がない

テスト自体に変更を加えていないのに、テストに合格したりしなかったりする場合は、テストの順序が正しいことを確認する必要があります。エミュレータとのやり取りのほとんどは非同期であるため、すべての非同期コードの順序が正しいことを再確認してください。順序を修正するには、Promise をチェーン化するか、await 表記を多数使用できます。

特に、以下の非同期オペレーションを確認してください。

initializeTestEnvironment などを使用したセキュリティルールの設定。
db.collection("users").doc("alice").get() などを使用したデータの読み書き。
assertSucceeds と assertFails を含む動作可能なアサーション。

エミュレータを初めて読み込むときにのみテストに合格する

エミュレータはステートフルです。書き込まれたすべてのデータをメモリに保存するので、エミュレータがシャットダウンするたびにデータは失われます。同じプロジェクト ID に対して複数のテストを実行している場合は、各テストで後続のテストに影響するデータが生成される可能性があります。次のいずれかの方法を使用すれば、この動作を回避できます。

テストごとに一意のプロジェクト ID を使用する。これを行う場合は、各テストの一環として initializeTestEnvironment を呼び出す必要があるのでご注意ください。ルールが自動的に読み込まれるのはデフォルトのプロジェクト ID のみです。
過去に書き込まれたデータを扱わないようにテストを再構成する（テストごとに異なるコレクションを使用するなど）。
テスト中に書き込まれたすべてのデータを削除する。

テストのセットアップが非常に複雑である

テストを設定する際に、Cloud Firestore Security Rules で実際には許可されない方法でデータを変更することが必要な場合もあります。ルールが原因でテストのセットアップが複雑になる場合は、セットアップのステップで RulesTestEnvironment.withSecurityRulesDisabled を使用すると、読み取りや書き込みによって PERMISSION_DENIED エラーがトリガーされなくなります。

その後、テストはそれぞれ RulesTestEnvironment.authenticatedContext と unauthenticatedContext を使用して、認証されたユーザーまたは認証されていないユーザーとして操作を実行できます。これにより、Cloud Firestore Security Rules によってさまざまなケースが正しく許可 / 拒否されるかどうかを検証できます。