Подключите свое приложение к эмулятору Cloud Firestore

Перед подключением приложения к эмулятору 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.
• Повышенная безопасность, поскольку, если ваш код случайно вызовет неэмулируемые (производственные) ресурсы, нет возможности изменить данные, использование и выставление счетов.
• Улучшенная автономная поддержка, поскольку нет необходимости в доступе в Интернет для загрузки конфигурации SDK.

Инструментируйте свое приложение для общения с эмуляторами

При запуске эмулятор Cloud Firestore создает базу данных по умолчанию и именованную базу данных для каждой конфигурации firestore в вашем файле firebase.json . Используйте файл firebase.json для явного назначения правил безопасности Cloud Firestore именованной базе данных.

Именованные базы данных также создаются неявно в ответ на любые вызовы SDK или REST API к эмулятору, которые ссылаются на определенную базу данных. Такие неявно созданные базы данных работают с открытыми правилами .

В настоящее время пользовательский интерфейс Emulator Suite поддерживает интерактивную работу с базой данных по умолчанию .

Платформы Android, Apple и веб-SDK

Настройте конфигурацию в приложении или тестовые классы для взаимодействия с Cloud Firestore следующим образом. Обратите внимание, что в следующих примерах код приложения подключается к базе данных проекта по умолчанию. Примеры использования дополнительных баз данных Cloud Firestore помимо базы данных по умолчанию см. в руководстве для нескольких баз данных .

// 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
}
EmulatorSuite.kt

// 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 = "127.0.0.1:8080"
settings.isPersistenceEnabled = false 
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

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

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

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

Для тестирования облачных функций , запускаемых событиями Firestore, с помощью эмулятора не требуется дополнительная настройка. Когда эмуляторы Firestore и Cloud Functions запущены, они автоматически работают вместе.

SDK администратора

Пакеты Firebase Admin SDK автоматически подключаются к эмулятору Cloud Firestore, когда установлена ​​переменная среды FIRESTORE_EMULATOR_HOST :

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Если ваш код выполняется внутри эмулятора Cloud Functions, идентификатор вашего проекта и другая конфигурация автоматически устанавливаются при вызове initializeApp .

Если вы хотите, чтобы ваш код Admin SDK подключался к общему эмулятору, работающему в другой среде, вам необходимо указать тот же идентификатор проекта, который вы установили с помощью интерфейса командной строки Firebase . Вы можете передать идентификатор проекта напрямую в initializeApp или установить переменную среды GCLOUD_PROJECT .

admin.initializeApp({ projectId: "your-project-id" });

export GCLOUD_PROJECT="your-project-id"

Очистите базу данных между тестами

Production Firestore не предоставляет платформенный метод SDK для очистки базы данных, но эмулятор Firestore предоставляет вам конечную точку REST специально для этой цели, которую можно вызвать из шага настройки/tearDown тестовой среды, из тестового класса или из оболочки (например, с помощью curl ) перед запуском теста. Вы можете использовать этот подход как альтернативу простому завершению процесса эмулятора.

В соответствующем методе выполните операцию HTTP DELETE, указав свой идентификатор проекта Firebase, например firestore-emulator-example , в следующую конечную точку:

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

Естественно, ваш код должен ожидать подтверждения REST о завершении или сбое сброса.

Вы можете выполнить эту операцию из оболочки:

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

Реализовав такой шаг, вы можете упорядочить тесты и запускать функции с уверенностью, что старые данные будут удалены между запусками и вы используете новую базовую тестовую конфигурацию.

Импорт и экспорт данных

База данных и облачное хранилище для эмуляторов Firebase позволяют экспортировать данные из работающего экземпляра эмулятора. Определите базовый набор данных для использования в модульных тестах или рабочих процессах непрерывной интеграции, а затем экспортируйте его для совместного использования в команде.

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, включая отслеживание оценки для правил безопасности 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 пытается точно воспроизвести поведение рабочей службы с некоторыми заметными ограничениями.

Поддержка нескольких баз данных для Cloud Firestore

В настоящее время пользовательский интерфейс Emulator Suite поддерживает интерактивное создание, редактирование, удаление, мониторинг запросов и визуализацию безопасности для базы данных по умолчанию, но не для дополнительных именованных баз данных.

Однако сам эмулятор создает именованную базу данных на основе конфигурации в вашем файле firebase.json и неявно в ответ на вызовы SDK или REST API.

Транзакции

В настоящее время эмулятор не реализует все поведение транзакций, наблюдаемое в рабочей среде. Когда вы тестируете функции, которые включают несколько одновременных операций записи в один документ, эмулятор может медленно выполнять запросы на запись. В некоторых случаях снятие блокировки может занять до 30 секунд. Рассмотрите возможность соответствующей корректировки тайм-аутов тестирования, если это необходимо.

Индексы

Эмулятор не отслеживает составные индексы и вместо этого выполняет любой допустимый запрос. Обязательно протестируйте свое приложение на реальном экземпляре Cloud Firestore, чтобы определить, какие индексы вам понадобятся.

Ограничения

Эмулятор не применяет все ограничения, установленные в рабочей среде. Например, эмулятор может разрешать транзакции, которые производственная служба отклонила бы как слишком большие. Убедитесь, что вы знакомы с задокументированными ограничениями и что вы разрабатываете свое приложение таким образом, чтобы заранее их избегать.

Что дальше?

• Подборку видеороликов и подробных практических примеров смотрите в учебном плейлисте Firebase Emulators .
• Изучите расширенные варианты использования, включающие тестирование правил безопасности и Firebase Test SDK: Test Security Rules (Firestore) .
• Поскольку триггерные функции — это типичная интеграция с Cloud Firestore, узнайте больше об эмуляторе Cloud Functions для Firebase в разделе Запуск функций локально .