在將您的應用程序連接到 Cloud Firestore 模擬器之前,請確保您了解整個 Firebase Local Emulator Suite 工作流程,並安裝和配置Local Emulator Suite 並查看其CLI 命令。
選擇一個 Firebase 項目
Firebase Local Emulator Suite 模擬單個 Firebase 項目的產品。
要選擇要使用的項目,請在啟動模擬器之前,在 CLI 中運行firebase use
。或者,您可以將--project
標誌傳遞給每個模擬器命令。
Local Emulator Suite 支持模擬真實的Firebase 項目和演示項目。
項目類型 | 特徵 | 與模擬器一起使用 |
---|---|---|
真實的 | 一個真正的 Firebase 項目是您創建和配置的項目(很可能是通過 Firebase 控制台)。 真實項目具有實時資源,例如數據庫實例、存儲桶、函數或您為該 Firebase 項目設置的任何其他資源。 | 在處理真實的 Firebase 項目時,您可以為任何或所有受支持的產品運行模擬器。 對於您未模擬的任何產品,您的應用程序和代碼將與實時資源(數據庫實例、存儲桶、函數等)交互。 |
演示 | 一個演示 Firebase 項目沒有真正的Firebase 配置,也沒有實時資源。這些項目通常通過代碼實驗室或其他教程訪問。 演示項目的項目 ID 具有 | 使用演示 Firebase 項目時,您的應用程序和代碼僅與模擬器交互。如果您的應用程序嘗試與未運行模擬器的資源進行交互,則該代碼將失敗。 |
我們建議您盡可能使用演示項目。好處包括:
- 設置更簡單,因為您無需創建 Firebase 項目即可運行模擬器
- 更強的安全性,因為如果您的代碼不小心調用了非模擬(生產)資源,就沒有數據更改、使用和計費的機會
- 更好的離線支持,因為無需訪問互聯網即可下載您的 SDK 配置。
檢測您的應用以與模擬器對話
Android、Apple 平台和 Web SDK
按如下方式設置您的應用內配置或測試類以與 Cloud Firestore 交互。
Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of // the host computer from an Android emulator. val firestore = Firebase.firestore firestore.useEmulator("10.0.2.2", 8080) firestore.firestoreSettings = firestoreSettings { isPersistenceEnabled = false }
Java
// 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);
迅速
let settings = Firestore.firestore().settings settings.host = "localhost:8080" settings.isPersistenceEnabled = false settings.isSSLEnabled = false Firestore.firestore().settings = settings
Web modular API
import { getFirestore, connectFirestoreEmulator } from "firebase/firestore"; // firebaseApps previously initialized using initializeApp() const db = getFirestore(); connectFirestoreEmulator(db, 'localhost', 8080);
Web namespaced API
// Firebase previously initialized using firebase.initializeApp(). var db = firebase.firestore(); if (location.hostname === "localhost") { db.useEmulator("localhost", 8080); }
無需額外設置即可使用模擬器測試由 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"
在測試之間清除數據庫
Production Firestore 不提供用於刷新數據庫的平台 SDK 方法,但 Firestore 模擬器為您提供了一個專門用於此目的的 REST 端點,可以從測試框架設置/拆卸步驟、測試類或 shell(例如, 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"
實施了這樣的步驟後,您可以對測試進行排序並觸發您的功能,並確信舊數據將在運行之間被清除,並且您正在使用新的基線測試配置。
導入導出數據
Firebase 模擬器的數據庫和 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選項卡以查看每個請求的詳細評估順序。
可視化規則評估報告
當您將安全規則添加到您的原型時,您可以使用 Local Emulator Suite 調試工具對其進行調試。
運行一套測試後,您可以訪問測試覆蓋率報告,其中顯示瞭如何評估每個安全規則。
要獲取報告,請在模擬器運行時查詢公開的端點。對於瀏覽器友好的版本,請使用以下 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 實例測試您的應用,以確定您需要哪些索引。
限制
模擬器不會強制執行生產中強制執行的所有限制。例如,模擬器可能允許生產服務因太大而拒絕的事務。確保您熟悉記錄在案的限制,並確保您設計的應用程序能夠主動避免這些限制。
接下來是什麼?
- 如需一組精選的視頻和詳細的操作示例,請關注Firebase Emulators Training Playlist 。
- 研究涉及安全規則測試和 Firebase 測試 SDK 的高級用例:測試安全規則 (Firestore) 。
- 由於觸發函數是與 Cloud Firestore 的典型集成,因此請在本地運行函數中了解有關 Cloud Functions for Firebase 模擬器的更多信息。