قم بتوصيل تطبيقك بمحاكي 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 الخاص بك.

صك تطبيقك للتحدث مع المحاكيات

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

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

حاليًا ، تدعم واجهة مستخدم Emulator Suite العمل التفاعلي مع قاعدة البيانات الافتراضية .

أنظمة Android و Apple و Web SDK

قم بإعداد التكوين داخل التطبيق أو فصول الاختبار للتفاعل مع Cloud Firestore على النحو التالي. لاحظ أنه في العينات التالية ، يتصل كود التطبيق بقاعدة بيانات المشروع الافتراضية. للحصول على أمثلة تتضمن قواعد بيانات 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 = "127.0.0.1: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, '127.0.0.1', 8080);

Web namespaced API

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

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

SDKs للمشرف

تتصل مجموعات 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 .

Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
متغيرات البيئة
export GCLOUD_PROJECT="your-project-id"

امسح قاعدة البيانات الخاصة بك بين الاختبارات

لا يوفر Production Firestore طريقة SDK للنظام الأساسي لمسح قاعدة البيانات ، لكن محاكي Firestore يمنحك نقطة نهاية REST خصيصًا لهذا الغرض ، والتي يمكن استدعاؤها من إعداد إطار اختبار / خطوة tearDown ، من فئة اختبار ، أو من 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> الطلبات لعرض تسلسل التقييم التفصيلي لكل طلب.

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 حقيقي لتحديد الفهارس التي ستحتاج إليها.

حدود

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

ماذا بعد؟