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

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

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

注: サーバー クライアント ライブラリは、すべての Firestore セキュリティ ルールをバイパスし、代わりに Google アプリケーションのデフォルト認証情報を使用して認証を行います。REST API または RPC API 用のサーバー クライアント ライブラリを使用する場合は、Firestore 用の Identity and Access Management（IAM）を設定してください。

クイックスタート

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

Firestore セキュリティ ルールについて

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

Firestore セキュリティ ルールには、次の 2 つが含まれています。

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

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

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

Firestore セキュリティ ルールの詳細については、Firestore セキュリティ ルールを使ってみるをご覧ください。

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

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 フィールドで指定されたルールを読み込みます。Firestore セキュリティ ルールが含まれているローカル ファイルの名前をこのフラグに指定すると、そのセキュリティ ルールがすべてのプロジェクトに適用されます。次で説明するとおり、ローカル ファイルパスを指定しない場合、あるいは 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 を使用して、認証状態を模倣するテストケースを実装します。

注: 以降の説明では、ルールの単体テスト用ライブラリの API の概要を示します。完全な API リファレンスのドキュメントもご覧ください。

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

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 トークンが添付されません。

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

// 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 互換）で使用できます。

ルール評価を可視化する

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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