將您的應用連接到 Cloud Firestore 模擬器

在將您的應用連接到 Cloud Firestore 模擬器之前，請確保您了解 Firebase Local Emulator Suite 的整體工作流程，並安裝和配置Local Emulator Suite 並查看其CLI 命令。

選擇一個 Firebase 項目

Firebase 本地模擬器套件模擬單個 Firebase 項目的產品。

要選擇要使用的項目，在啟動模擬器之前，請在 CLI 中在您的工作目錄中運行firebase use 。或者，您可以將--project標誌傳遞給每個模擬器命令。

Local Emulator Suite 支持模擬真實的Firebase 項目和演示項目。

項目類型特徵與模擬器一起使用
真實的

真正的 Firebase 項目是您創建和配置的項目（很可能通過 Firebase 控制台）。

真實項目具有實時資源，例如數據庫實例、存儲桶、函數或您為該 Firebase 項目設置的任何其他資源。

在處理真正的 Firebase 項目時，您可以為任何或所有受支持的產品運行模擬器。

對於您未模擬的任何產品，您的應用程序和代碼將與實時資源（數據庫實例、存儲桶、函數等）進行交互。

演示

演示 Firebase 項目沒有真正的Firebase 配置，也沒有實時資源。這些項目通常通過代碼實驗室或其他教程訪問。

演示項目的項目 ID 具有demo-前綴。

使用演示 Firebase 項目時，您的應用和代碼僅與模擬器交互。如果您的應用程序嘗試與未運行模擬器的資源進行交互，則該代碼將失敗。

我們建議您盡可能使用演示項目。好處包括：

  • 設置更簡單，因為您無需創建 Firebase 項目即可運行模擬器
  • 更強的安全性，因為如果您的代碼意外調用非模擬（生產）資源，則不會發生數據更改、使用和計費
  • 更好的離線支持，因為無需訪問互聯網即可下載您的 SDK 配置。

檢測您的應用程序以與模擬器對話

Android、Apple 平台和 Web SDK

設置應用內配置或測試類以與 Cloud Firestore 交互，如下所示。

安卓
        // 10.0.2.2 is the special IP address to connect to the 'localhost' of
        // the host computer from an Android emulator.
        FirebaseFirestore firestore = FirebaseFirestore.getInstance();
        firestore.useEmulator("10.0.2.2", 8080);

        FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
                .setPersistenceEnabled(false)
                .build();
        firestore.setFirestoreSettings(settings);
EmulatorSuite.java
迅速
let settings = Firestore.firestore().settings
settings.host = "localhost:8080"
settings.isPersistenceEnabled = false 
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Web version 9

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, 'localhost', 8080);
fs_emulator_connect.js

Web version 8

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("localhost", 8080);
}
emulator-suite.js

無需額外設置即可使用模擬器測試由 Firestore 事件觸發的Cloud Functions。當 Firestore 和 Cloud Functions 模擬器都在運行時，它們會自動協同工作。

管理 SDK

設置FIRESTORE_EMULATOR_HOST環境變量後，Firebase Admin SDK 會自動連接到 Cloud Firestore 模擬器：

export FIRESTORE_EMULATOR_HOST="localhost:8080"

如果您的代碼在 Cloud Functions 模擬器中運行，您的項目 ID 和其他配置將在調用initalizeApp時自動設置。

如果您希望您的 Admin SDK 代碼連接到在另一個環境中運行的共享模擬器，則需要指定您使用 Firebase CLI 設置的相同項目 ID 。您可以將項目 ID 直接傳遞給initializeApp或設置GCLOUD_PROJECT環境變量。

Node.js 管理 SDK
admin.initializeApp({ projectId: "your-project-id" });
環境變量
export GCLOUD_PROJECT="your-project-id"

在測試之間清除數據庫

生產 Firestore 沒有提供用於刷新數據庫的平台 SDK 方法，但 Firestore 模擬器為您提供了專門用於此目的的 REST 端點，可以從測試框架設置/拆卸步驟、測試類或外殼程序調用該端點（例如, curl ) 在測試開始之前。您可以使用此方法作為簡單關閉模擬器進程的替代方法。

在適當的方法中，執行 HTTP DELETE 操作，將您的 Firebase projectID（例如firestore-emulator-example ）提供給以下端點：

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

自然，您的代碼應該等待 REST 確認刷新完成或失敗。

您可以從 shell 執行此操作：

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

實施了這樣的步驟後，您可以對測試進行排序並觸發您的函數，確信舊數據將在運行之間被清除，並且您正在使用新的基線測試配置。

導入和導出數據

數據庫和 Cloud Storage 模擬器允許您從正在運行的模擬器實例中導出數據。定義要在單元測試或持續集成工作流中使用的基線數據集，然後將其導出以在團隊之間共享。

firebase emulators:export ./dir

在測試中，在模擬器啟動時，導入基線數據。

firebase emulators:start --import=./dir

您可以指示模擬器在關機時導出數據，可以指定導出路徑，也可以簡單地使用傳遞給--import標誌的路徑。

firebase emulators:start --import=./dir --export-on-exit

這些數據導入和導出選項也適用於firebase emulators:exec命令。有關更多信息，請參閱模擬器命令參考。

可視化安全規則活動

在完成原型和測試循環時，您可以使用 Local Emulator Suite 提供的可視化工具和報告。

使用請求監視器

Cloud Firestore 模擬器可讓您在 Emulator Suite UI 中可視化客戶端請求，包括 Firebase 安全規則的評估跟踪。

打開Firestore > Requests選項卡以查看每個請求的詳細評估順序。

Firestore 模擬器請求監視器顯示安全規則評估

可視化規則評估報告

當您將安全規則添加到您的原型時，您可以使用本地仿真器套件調試工具對其進行調試。

運行一套測試後，您可以訪問測試覆蓋率報告，顯示您的每個安全規則是如何評估的。

要獲取報告，請在模擬器運行時查詢其暴露的端點。對於瀏覽器友好的版本，請使用以下 URL：

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

這會將您的規則分解為表達式和子表達式，您可以將鼠標懸停以獲取更多信息，包括評估的數量和返回的值。對於此數據的原始 JSON 版本，請在查詢中包含以下 URL：

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

在這裡，報告的 HTML 版本突出顯示了引發未定義和空值錯誤的評估：

Cloud Firestore 模擬器與生產環境有何不同

Cloud Firestore 模擬器嘗試忠實地複制生產服務的行為，但存在一些明顯的限制。

交易

模擬器當前並未實現生產中看到的所有事務行為。當您測試涉及多個並發寫入一個文檔的功能時，模擬器完成寫入請求可能會很慢。在某些情況下，鎖定可能需要長達 30 秒才能釋放。如果需要，請考慮相應地調整測試超時。

索引

模擬器不跟踪複合索引，而是執行任何有效的查詢。確保針對真實的 Cloud Firestore 實例測試您的應用，以確定您需要哪些索引。

限制

模擬器不會強制執行生產中強制執行的所有限制。例如，模擬器可能允許因生產服務太大而被拒絕的事務。確保您熟悉記錄在案的限制，並確保您在設計應用時主動避免這些限制。

接下來是什麼？