قم بتوصيل تطبيقك بمحاكي Cloud Firestore

قبل توصيل تطبيقك بمحاكي Cloud Firestore، تأكد من فهمك لسير عمل Firebase Local Emulator Suite الشامل ، ومن تثبيت Local Emulator Suite وتكوينه ومراجعة أوامر واجهة سطر الأوامر (CLI) الخاصة به.

اختر مشروع Firebase

يحاكي Firebase Local Emulator Suite المنتجات لمشروع Firebase واحد.

لتحديد المشروع المراد استخدامه، قبل بدء تشغيل المحاكيات، قم بتشغيل firebase use في سطر الأوامر (CLI) في دليل العمل الخاص بك. أو يمكنك تمرير علامة --project إلى كل أمر محاكي.

يدعم Local Emulator Suite محاكاة مشاريع Firebase الحقيقية والمشاريع التجريبية .

ننصحك باستخدام المشاريع التجريبية حيثما أمكن ذلك. تشمل الفوائد ما يلي:

• إعداد أسهل، حيث يمكنك تشغيل المحاكيات دون إنشاء مشروع Firebase
• أمان أقوى، لأنه إذا استدعت التعليمات البرمجية الخاصة بك عن طريق الخطأ موارد غير مقلدة (إنتاجية)، فلن تكون هناك فرصة لتغيير البيانات والاستخدام والفوترة
• دعم أفضل في وضع عدم الاتصال، نظرًا لعدم الحاجة إلى الوصول إلى الإنترنت لتنزيل تكوين SDK الخاص بك.

قم بتجهيز تطبيقك للتحدث مع المحاكيات

عند بدء التشغيل، يقوم محاكي Cloud Firestore بإنشاء قاعدة بيانات افتراضية وقاعدة بيانات مسماة لكل تكوين firestore في ملف firebase.json الخاص بك. استخدم ملف firebase.json الخاص بك لتعيين قواعد أمان Cloud Firestore بشكل صريح لقاعدة بيانات مسماة.

يتم أيضًا إنشاء قواعد البيانات المسماة ضمنيًا استجابةً لأي استدعاءات SDK أو REST API إلى المحاكي التي تشير إلى قاعدة بيانات محددة. تعمل قواعد البيانات التي تم إنشاؤها ضمنيًا بقواعد مفتوحة .

حاليًا، تدعم Emulator Suite UI العمل التفاعلي مع قاعدة البيانات الافتراضية .

منصات 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 للمشرف

تتصل حزم SDK الخاصة بمسؤول Firebase تلقائيًا بمحاكي 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 خصيصًا لهذا الغرض، والتي يمكن استدعاؤها من خطوة إعداد/تفكيك إطار عمل الاختبار، أو من فئة اختبار، أو من Shell (على سبيل المثال ، مع 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 > علامة التبويب الطلبات لعرض تسلسل التقييم التفصيلي لكل طلب.

تصور تقارير تقييمات القواعد

أثناء قيامك بإضافة قواعد الأمان إلى النموذج الأولي الخاص بك، يمكنك تصحيح الأخطاء باستخدام أدوات تصحيح الأخطاء 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 Emulator تكرار سلوك خدمة الإنتاج بأمانة مع بعض القيود الملحوظة.

دعم قاعدة بيانات متعددة لـ Cloud Firestore

حاليًا، تدعم واجهة مستخدم Emulator Suite الإنشاء التفاعلي، والتحرير، والحذف، ومراقبة الطلبات، وتصور الأمان لقاعدة البيانات الافتراضية، ولكن ليس قواعد بيانات مسماة إضافية.

ومع ذلك، يقوم المحاكي نفسه بإنشاء قاعدة بيانات مسماة بناءً على التكوين الموجود في ملف firebase.json الخاص بك وضمنيًا استجابةً لاستدعاءات SDK أو REST API.

المعاملات

لا يقوم المحاكي حاليًا بتنفيذ كافة سلوكيات المعاملات التي تظهر في الإنتاج. عند اختبار الميزات التي تتضمن عدة عمليات كتابة متزامنة لمستند واحد، قد يكون المحاكي بطيئًا في إكمال طلبات الكتابة. في بعض الحالات، قد يستغرق تحرير الأقفال ما يصل إلى 30 ثانية. فكر في تعديل مهلات الاختبار وفقًا لذلك، إذا لزم الأمر.

الفهارس

لا يقوم المحاكي بتتبع الفهارس المركبة وبدلاً من ذلك سيقوم بتنفيذ أي استعلام صالح. تأكد من اختبار تطبيقك مقابل مثيل حقيقي لـ Cloud Firestore لتحديد الفهارس التي ستحتاج إليها.

حدود

لا يفرض المحاكي جميع الحدود المفروضة في الإنتاج. على سبيل المثال، قد يسمح المحاكي بالمعاملات التي قد يتم رفضها باعتبارها كبيرة جدًا بواسطة خدمة الإنتاج. تأكد من أنك على دراية بالحدود الموثقة وأنك تصمم تطبيقك لتجنبها بشكل استباقي.

ماذا بعد؟

• للحصول على مجموعة منسقة من مقاطع الفيديو وأمثلة تفصيلية عن كيفية الاستخدام، اتبع قائمة تشغيل تدريب Firebase Emulators .
• التحقيق في حالات الاستخدام المتقدمة التي تتضمن اختبار قواعد الأمان وFirebase Test SDK: اختبار قواعد الأمان (Firestore) .
• نظرًا لأن الوظائف التي تم تشغيلها تمثل تكاملًا نموذجيًا مع Cloud Firestore، فتعرف على المزيد حول Cloud Functions لمحاكي Firebase في Run jobs محليًا .