Подключите свое приложение к эмулятору 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 .

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

Чтобы работать с базами данных по умолчанию и именованными базами данных в интерактивном режиме в Emulator Suite UI , в адресной строке браузера обновите URL-адрес, чтобы выбрать базу данных по умолчанию или именованную базу данных.

• Например, чтобы просмотреть данные в экземпляре по умолчанию, обновите URL-адрес на localhost:4000/firestore/default/data
• Чтобы просмотреть экземпляр с именем ecommerce , обновите его до localhost:4000/firestore/ecommerce/data .

Платформы 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.cacheSettings = MemoryCacheSettings()
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 запущены, он�� автоматически работают вместе.

Admin SDK

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

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

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

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

export GCLOUD_PROJECT="your-project-id"

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

Production 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"

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

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

База данных и Cloud Storage for 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 UI , включая отслеживание оценки Firebase Security Rules .

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

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

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

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

Транзакции

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

Индексы

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

Пределы

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

Что дальше?

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

Прежде чем подключать приложение к эмулятору 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 .

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

Чтобы работать с базами данных по умолчанию и именованными базами данных в интерактивном режиме в Emulator Suite UI , в адресной строке браузера обновите URL-адрес, чтобы выбрать базу данных по умолчанию или именованную базу данных.

• Например, чтобы просмотреть данные в экземпляре по умолчанию, обновите URL-адрес на localhost:4000/firestore/default/data
• Чтобы просмотреть экземпляр с именем ecommerce , обновите его до localhost:4000/firestore/ecommerce/data .

Платформы 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.cacheSettings = MemoryCacheSettings()
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 запущены, они автоматически работают вместе.

Admin SDK

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

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

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

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

export GCLOUD_PROJECT="your-project-id"

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

Production 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"

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

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

База данных и Cloud Storage for 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 UI , включая отслеживание оценки Firebase Security Rules .

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

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

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

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

Транзакции

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

Индексы

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

Пределы

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

Что дальше?

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