قبل ربط تطبيقك بمحاكي Cloud Firestore، تأكَّد من فهم سير عمل Firebase Local Emulator Suite العام، بالإضافة إلى تثبيته وضبط إعداداته Local Emulator Suite ومراجعة أوامر CLI.
اختيار مشروع في Firebase
يحاكي Firebase Local Emulator Suite المنتجات لمشروع واحد على Firebase.
لتحديد المشروع المراد استخدامه، قبل بدء تشغيل الأجهزة المحاكية، في واجهة سطر الأوامر
firebase use
في دليل العمل. أو يمكنك تمرير
علامة "--project
" على كل محاكي
الأمر.
تتيح Local Emulator Suite إمكانية محاكاة مشاريع Firebase الحقيقية. لإصدار تجريبي من المشاريع.
نوع المشروع | الميزات | الاستخدام مع المحاكيات |
---|---|---|
حقيقي |
مشروع Firebase الحقيقي هو المشروع الذي أنشأته وإعداده (على الأرجح عبر وحدة تحكُّم Firebase). تحتوي المشروعات الحقيقية على موارد مباشرة، مثل مثيلات قاعدة البيانات والتخزين أو المجموعات أو الدوال أو أي مورد آخر أعددته لمنصة Firebase مشروعك. |
عند العمل مع مشاريع Firebase حقيقية، يمكنك تشغيل أدوات محاكاة لأي أو جميع المنتجات المعتمدة. بالنسبة إلى أي منتجات لا تحاكيها، ستتم إزالة التطبيقات والرموز البرمجية. التفاعل مع المورد المباشر (مثيل قاعدة البيانات، والتخزين الحزمة أو الدالة وما إلى ذلك). |
تجريبي |
لا يتضمن مشروع Firebase التجريبي أي إعداد حقيقي في Firebase لا تتوفر موارد مباشرة. عادة ما يتم الوصول إلى هذه المشروعات من خلال دروس تطبيقية حول الترميز أو برامج تعليمية أخرى. تتضمّن أرقام تعريف المشاريع الخاصة بالمشاريع التجريبية البادئة |
عند العمل مع مشاريع Firebase التجريبية، تتفاعل تطبيقاتك ورمزك مع المحاكي فقط. إذا حاول تطبيقك التفاعل مع مورد إذا كان المحاكي لا يعمل، فسيفشل هذا الرمز. |
ننصحك باستخدام المشاريع التجريبية كلما أمكن ذلك. تتضمّن المزايا ما يلي:
- إعداد أسهل، حيث يمكنك تشغيل أدوات المحاكاة دون الحاجة إلى إنشاء مشروع في Firebase
- مستوى أمان أعلى، لأنّه إذا استخدَم الرمز الخاص بك عن طريق الخطأ تطبيقات لم تتم محاكاتها (الإنتاج)، ليست هناك فرصة لتغيير البيانات واستخدامها والفوترة
- دعم أفضل في وضع عدم الاتصال، نظرًا لعدم الحاجة إلى الاتصال بالإنترنت من أجل تنزيل إعدادات حزمة SDK
استخدِم تطبيقك للتواصل مع المحاكيات
عند بدء التشغيل، ينشئ محاكي Cloud Firestore قاعدة بيانات تلقائية وعنوانًا
لكل إعداد firestore
في
ملف firebase.json
كما يتم إنشاء قواعد البيانات المعنونة ضمنيًا استجابةً لأي حزم SDK أو تطلب واجهة برمجة التطبيقات REST من المحاكي الرجوع إلى قاعدة بيانات معينة. مثل تعمل قواعد البيانات المنشأة بشكل ضمني باستخدام قواعد مفتوحة.
للعمل مع قواعد البيانات الافتراضية والمسماة بشكل تفاعلي في Emulator Suite UI، في شريط عناوين المتصفّح، عدِّل عنوان URL لاختياره. إما قاعدة بيانات افتراضية أو قاعدة بيانات مُعنوَنة.
- على سبيل المثال، لتصفّح البيانات في المثيل التلقائي، عدِّل عنوان URL إلى
localhost:4000/firestore/default/data
- للتصفّح في نسخة افتراضية باسم
ecommerce
، يجب التعديل إلىlocalhost:4000/firestore/ecommerce/data
أنظمة Android الأساسية وApple وحزم تطوير البرامج (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);
Swift
let settings = Firestore.firestore().settings settings.host = "127.0.0.1:8080" settings.cacheSettings = MemoryCacheSettings() settings.isSSLEnabled = false Firestore.firestore().settings = settings
Web
import { getFirestore, connectFirestoreEmulator } from "firebase/firestore"; // firebaseApps previously initialized using initializeApp() const db = getFirestore(); connectFirestoreEmulator(db, '127.0.0.1', 8080);
Web
// 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 قيد التشغيل، فإنها تعمل معًا تلقائيًا.
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.
يمكنك ضبط رقم تعريف المشروع على initializeApp
مباشرةً أو ضبط
متغيّر البيئة GCLOUD_PROJECT
.
حزمة تطوير البرامج (SDK) لمشرف Node.js
admin.initializeApp({ projectId: "your-project-id" });
متغيّر البيئة
export GCLOUD_PROJECT="your-project-id"
محو قاعدة البيانات بين الاختبارات
لا توفّر حزمة تطوير البرامج (SDK) الخاصة بالإنتاج على الإطلاق طريقة لتجميع قاعدة البيانات، إلا أنّ محاكي Firestore يمنحك نقطة نهاية REST خصيصًا لهذا الغرض، والتي يمكن استدعاؤها من خلال خطوة إعداد إطار عمل تجريبي أو خطوة TearDown أو من صف تجريبي أو من واجهة الأوامر (مثل curl
) قبل بدء الاختبار. يمكنك استخدام هذا الأسلوب كبديل لإيقاف عملية المحاكي ببساطة.
بطريقة مناسبة، يمكنك تنفيذ عملية حذف HTTP، حيث تتم إضافة
رقم تعريف مشروع 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.
المعاملات
لا ينفِّذ المحاكي حاليًا جميع سلوكيات المعاملات كما هو الحال في الإنتاج. عند اختبار ميزات تتضمن عدة عمليات الكتابة المتزامنة على مستند واحد، فقد يكون المحاكي بطيئًا في إكمال الكتابة الطلبات. في بعض الحالات، قد يستغرق فتح القفل مدة تصل إلى 30 ثانية. وننصحك بتعديل مهلات الاختبار وفقًا لذلك، إذا لزم الأمر.
المؤشرات
لا يتتبّع المحاكي الفهارس المركّبة وبدلاً من ذلك سينفذ أيًا منها استعلام صالح. احرص على اختبار تطبيقك بالمقارنة مع Cloud Firestore حقيقي. مثال لتحديد الفهارس التي ستحتاج إليها.
الحدود
لا يفرض المحاكي جميع الحدود المفروضة في قناة الإصدار العلني. على سبيل المثال: قد يسمح المحاكي بالمعاملات التي سيتم رفضها بسبب حجمها الكبير جدًا بواسطة خدمة الإنتاج. تأكد من أنك على دراية الحدود الموثقة وأنك تصمم تطبيقك من أجل تجنبها بشكل استباقي.
ما هي الخطوات التالية؟
- للحصول على مجموعة منظَّمة من الفيديوهات وأمثلة مفصّلة حول كيفية الاستخدام، يمكنك متابعة قائمة التشغيل الخاصة بالتدريب على محاكيات Firebase.
- يمكنك التحقيق في حالات الاستخدام المتقدّمة التي تشمل اختبار قواعد الأمان وحزمة تطوير البرامج (SDK) التجريبية لاختبار Firebase: اختبار قواعد الأمان (Firestore).
- بما أنّ الدوال المُفعَّلة هي عملية دمج نموذجية مع Cloud Firestore، يمكنك الاطّلاع على مزيد من المعلومات حول محاكي "Cloud Functions for Firebase" من خلال تنفيذ الدوال على الجهاز: