Подключите свое приложение к эмулятору 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 — это тот, который вы создали и настроили (скорее всего, через консоль Firebase).

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

При работе с реальными проектами Firebase вы можете запускать эмуляторы для любого или всех поддерживаемых продуктов.

Для любых продуктов, которые вы не эмулируете, ваши приложения и код будут взаимодействовать с активным ресурсом (экземпляром базы данных, сегментом хранилища, функцией и т. д.).

Демо

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

Идентификаторы проектов для демонстрационных проектов имеют префикс demo- .

При работе с демонстрационными проектами Firebase ваши приложения и код взаимодействуют только с эмуляторами. Если ваше приложение попытается взаимодействовать с ресурсом, для которого не запущен эмулятор, этот код завершится ошибкой.

Мы рекомендуем вам использовать демонстрационные проекты везде, где это возможно. Преимущества включают в себя:

  • Простая настройка, так как вы можете запускать эмуляторы, даже не создавая проект Firebase.
  • Повышенная безопасность, поскольку, если ваш код случайно вызывает неэмулируемые (производственные) ресурсы, нет никаких шансов на изменение данных, использование и выставление счетов.
  • Улучшенная автономная поддержка, поскольку нет необходимости в доступе в Интернет для загрузки конфигурации SDK.

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

Платформы Android, Apple и веб-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);
Быстрый
let settings = Firestore.firestore().settings
settings.host = "localhost:8080"
settings.isPersistenceEnabled = false 
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

Web version 9

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

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

Web version 8

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

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

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

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

export FIRESTORE_EMULATOR_HOST="localhost:8080"

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

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

Пакет SDK для администрирования Node.js
admin.initializeApp({ projectId: "your-project-id" });
Переменная среды
export GCLOUD_PROJECT="your-project-id"

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

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

Монитор запросов эмулятора Firestore, показывающий оценки правил безопасности

Визуализация отчетов об оценке правил

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