Join us for Firebase Summit on November 10, 2021. Tune in to learn how Firebase can help you accelerate app development, release with confidence, and scale with ease. Register

اختبر قواعد أمان Cloud Firestore

أثناء قيامك بإنشاء تطبيقك ، قد ترغب في تأمين الوصول إلى قاعدة بيانات Cloud Firestore. ومع ذلك ، قبل بدء التشغيل ، ستحتاج إلى المزيد من قواعد أمان Cloud Firestore الأكثر دقة. مع المحاكي سحابة Firestore، بالإضافة إلى النماذج واختبار التطبيق الخاص بك الملامح العامة والسلوك ، يمكنك كتابة اختبارات الوحدة التي تحقق سلوك قواعد الأمن Firestore السحب الخاصة بك.

بداية سريعة

لبضع حالات الاختبار الأساسية مع قواعد بسيطة، محاولة الخروج من عينة التشغيل السريع .

فهم قواعد أمان Cloud Firestore

تنفيذ مصادقة Firebase و الكلمة الدلالية ضوابط الأمن Firestore للمصادقة serverless، إذن، والتحقق من صحة البيانات عند استخدام مكتبات العميل المحمولة وشبكة الإنترنت.

تتضمن قواعد أمان Cloud Firestore قطعتين:

  1. A match بيان ان يحدد الوثائق في قاعدة البيانات الخاصة بك.
  2. و allow التعبير التي تتحكم في الوصول إلى تلك الوثائق.

تتحقق مصادقة Firebase من بيانات اعتماد المستخدمين وتوفر الأساس لأنظمة الوصول المستندة إلى المستخدم والمستندة إلى الأدوار.

يتم تقييم كل طلب قاعدة بيانات من مكتبة Cloud Firestore للهاتف المحمول / الويب وفقًا لقواعد الأمان الخاصة بك قبل قراءة أو كتابة أي بيانات. إذا كانت القواعد تمنع الوصول إلى أي من مسارات المستند المحددة ، يفشل الطلب بأكمله.

تعلم المزيد عن قواعد الأمن Firestore الغيمة في الشروع في العمل مع سحابة قواعد الأمن Firestore .

قم بتثبيت المحاكي

لتثبيت المحاكي سحابة Firestore، استخدم Firebase CLI ثم قم بتشغيل الأمر التالي:

firebase setup:emulators:firestore

قم بتشغيل المحاكي

ابدأ بتهيئة مشروع Firebase في دليل العمل الخاص بك. هذا هو الخطوة الأولى شيوعا عند استخدام Firebase CLI .

firebase init

ابدأ المحاكي باستخدام الأمر التالي. سيتم تشغيل المحاكي حتى تقتل العملية:

firebase emulators:start --only firestore

في كثير من الحالات ، تريد بدء تشغيل المحاكي ، وتشغيل مجموعة اختبار ، ثم إيقاف تشغيل المحاكي بعد تشغيل الاختبارات. يمكنك القيام بذلك بسهولة باستخدام emulators:exec الأوامر:

firebase emulators:exec --only firestore "./my-test-script.sh"

عند بدء تشغيل المحاكي سيحاول التشغيل على المنفذ الافتراضي (8080). يمكنك تغيير المنفذ المحاكي عن طريق تعديل "emulators" القسم الخاص firebase.json الملف:

{
  // ...
  "emulators": {
    "firestore": {
      "port": "YOUR_PORT"
    }
  }
}

قبل تشغيل المحاكي

قبل البدء في استخدام المحاكي ، ضع في اعتبارك ما يلي:

  • سوف المحاكي تحميل في البداية القواعد المحددة في firestore.rules مجال الخاص بك firebase.json الملف. تتوقع اسم ملف محلي يحتوي على قواعد أمان Cloud Firestore الخاصة بك وتطبق هذه القواعد على جميع المشاريع. إذا لم تقم بتوفير مسار الملف المحلي أو استخدام loadFirestoreRules الطريقة كما هو موضح أدناه، يعامل المحاكي جميع المشاريع وجود قواعد مفتوحة.
  • بينما معظم Firebase تطوير البرامج العمل مع محاكاة مباشرة، إلا أن @firebase/rules-unit-testing الدعم مكتبة ساخرا auth في قواعد الأمن، جعل وحدة اختبارات أسهل بكثير. بالإضافة إلى ذلك ، تدعم المكتبة بعض الميزات الخاصة بالمحاكي مثل مسح جميع البيانات ، كما هو موضح أدناه.
  • ستقبل المحاكيات أيضًا رموز Firebase Auth المميزة للإنتاج المقدمة من خلال Client SDKs وتقييم القواعد وفقًا لذلك ، مما يسمح بربط تطبيقك مباشرةً بالمحاكيات في التكامل والاختبارات اليدوية.

قم بإجراء اختبارات الوحدة المحلية

قم بتشغيل اختبارات الوحدة المحلية باستخدام الإصدار 9 من JavaScript SDK

يوزع Firebase مكتبة اختبار وحدة قواعد الأمان مع الإصدار 9 من JavaScript SDK والإصدار 8 SDK. تختلف واجهات برمجة التطبيقات الخاصة بالمكتبة اختلافًا كبيرًا. نوصي بمكتبة اختبار الإصدار 9 ، وهي أكثر انسيابية وتتطلب إعدادًا أقل للاتصال بالمحاكيات وبالتالي تجنب الاستخدام العرضي لموارد الإنتاج بأمان. من أجل التوافق الى الوراء، ونحن نواصل جعل مكتبة اختبار V8 المتاحة .

استخدام @firebase/rules-unit-testing وحدة لتتفاعل مع المحاكي أن يعمل محليا. إذا كنت تحصل على مهلة أو ECONNREFUSED الأخطاء، انقر نقرا مزدوجا الاختيار المحاكي يعمل فعلا.

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

مكتبة v9 Rules Unit Testing دائمًا على دراية بالمحاكيات ولا تلمس أبدًا موارد الإنتاج الخاصة بك.

يمكنك استيراد المكتبة باستخدام عبارات الاستيراد المعيارية v9. على سبيل المثال:

import {
  assertFails,
  assertSucceeds,
  initializeTestEnvironment,
  RulesTestEnvironment,
} from "@firebase/rules-unit-testing"

// Use `const { … } = require("@firebase/rules-unit-testing")` if imports are not supported
// Or we suggest `const testing = require("@firebase/rules-unit-testing")` if necessary.

بمجرد الاستيراد ، يتضمن تنفيذ اختبارات الوحدة ما يلي:

  • إنشاء وتكوين RulesTestEnvironment مع دعوة initializeTestEnvironment .
  • إعداد بيانات الاختبار من دون التسبب قوانين، وذلك باستخدام أسلوب الراحة التي تسمح لك مؤقتا تجاوز لهم، RulesTestEnvironment.withSecurityRulesDisabled .
  • إعداد اختبار جناح ولكل اختبار قبل / بعد السنانير مع دعوات لتنظيف بيانات الاختبار والبيئة، مثل RulesTestEnvironment.cleanup() أو RulesTestEnvironment.clearFirestore() .
  • تنفيذ حالات الاختبار أن الدول المصادقة تقليد باستخدام RulesTestEnvironment.authenticatedContext و RulesTestEnvironment.unauthenticatedContext .

الطرق الشائعة ووظائف المنفعة

انظر أيضا طرق الاختبار-منافس معين في SDK V9 .

initializeTestEnvironment() => RulesTestEnvironment

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

وظيفة تقبل كائن اختياري تحديد TestEnvironmentConfig ، والتي يمكن أن تتكون من هوية المشروع ومحاكي إعدادات التكوين.

let testEnv = await initializeTestEnvironment({
  projectId: "demo-project-1234",
  firestore: {
    rules: fs.readFileSync("firestore.rules", "utf8"),
  },
});

RulesTestEnvironment.authenticatedContext({ user_id: string, tokenOptions?: TokenOptions }) => RulesTestContext

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

استخدام كائن سياق اختبار عاد في الاختبارات الخاصة بك للوصول إلى أي حالات محاكي تكوين، بما في ذلك تكوين مع initializeTestEnvironment .

// Assuming a Firestore app and the Firestore emulator for this example
import { setDoc } from "firebase/firestore";

const alice = testEnv.authenticatedContext("alice", { … });
// Use the Firestore instance associated with this context
await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

RulesTestEnvironment.unauthenticatedContext() => RulesTestContext

هذا الأسلوب بإنشاء RulesTestContext ، الذي يتصرف وكأنه عميل الذي لم يتم تسجيل في طريق المصادقة. الطلبات التي تم إنشاؤها عبر السياق الذي تم إرجاعه لن يتم إرفاق رموز Firebase Auth الخاصة بها.

استخدام كائن سياق اختبار عاد في الاختبارات الخاصة بك للوصول إلى أي حالات محاكي تكوين، بما في ذلك تكوين مع initializeTestEnvironment .

// Assuming a Cloud Storage app and the Storage emulator for this example
import { getStorage, ref, deleteObject } from "firebase/storage";

const alice = testEnv.unauthenticatedContext();

// Use the Cloud Storage instance associated with this context
const desertRef = ref(alice.storage(), 'images/desert.jpg');
await assertSucceeds(deleteObject(desertRef));

RulesTestEnvironment.withSecurityRulesDisabled()

قم بتشغيل وظيفة إعداد اختبار مع سياق يتصرف كما لو تم تعطيل قواعد الأمان.

تأخذ هذه الطريقة وظيفة رد الاتصال ، والتي تأخذ سياق تجاوز قواعد الأمان وتعيد وعدًا. سيتم تدمير السياق بمجرد أن يحل الوعد / يرفض.

RulesTestEnvironment.cleanup()

هذه الطريقة يدمر كل RulesTestContexts التي تم إنشاؤها في بيئة اختبار وينظف الموارد الكامنة، والسماح لخروج نظيفة.

هذه الطريقة لا تغير حالة المحاكيات بأي شكل من الأشكال. لإعادة تعيين البيانات بين الاختبارات ، استخدم طريقة البيانات الواضحة الخاصة بمحاكي التطبيق.

assertSucceeds(pr: Promise<any>)) => Promise<any>

هذه وظيفة حالة اختبار.

تؤكد الوظيفة أنه سيتم حل الوعد المقدم الذي يغلف عملية المحاكي بدون انتهاكات لقواعد الأمان.

await assertSucceeds(setDoc(alice.firestore(), '/users/alice'), { ... });

assertFails(pr: Promise<any>)) => Promise<any>

هذه وظيفة حالة اختبار.

تؤكد الوظيفة أن الوعد المقدم الذي يغلف عملية المحاكي سيتم رفضه بانتهاك قواعد الأمان.

await assertFails(setDoc(alice.firestore(), '/users/bob'), { ... });

طرق خاصة بالمحاكي

انظر أيضا طرق الاختبار المشترك والوظائف ذات المنفعة في SDK V9 .

RulesTestEnvironment.clearFirestore() => Promise<void>

هذه الطريقة يزيل البيانات في قاعدة البيانات Firestore الذي ينتمي إلى projectId تكوين المضاهاة Firestore.

RulesTestContext.firestore(settings?: Firestore.FirestoreSettings) => Firestore;

تحصل هذه الطريقة على مثيل Firestore لسياق الاختبار هذا. يمكن استخدام مثيل Firebase JS Client SDK الذي تم إرجاعه مع واجهات برمجة تطبيقات SDK للعميل (الإصدار 9 المعياري أو الإصدار 9 المتوافق).

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

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

فتح Firestore> علامة التبويب طلبات لعرض تسلسل تقييم مفصل لكل طلب.

Firestore طلبات المحاكي مراقب يعرض تقييمات قواعد الأمان

توليد تقارير الاختبار

بعد إجراء مجموعة من الاختبارات ، يمكنك الوصول إلى تقارير التغطية الاختبارية التي توضح كيفية تقييم كل قاعدة من قواعد الأمان الخاصة بك.

للحصول على التقارير ، استعلم عن نقطة نهاية مكشوفة على المحاكي أثناء تشغيله. للحصول على إصدار متوافق مع المتصفح ، استخدم عنوان URL التالي:

http://localhost:8080/emulator/v1/projects/<project_id>:ruleCoverage.html

يؤدي هذا إلى تقسيم القواعد إلى تعبيرات وتعبيرات فرعية يمكنك تمرير الماوس فوقها للحصول على مزيد من المعلومات ، بما في ذلك عدد التقييمات والقيم التي يتم إرجاعها. للحصول على نسخة JSON الأولية من هذه البيانات ، قم بتضمين عنوان URL التالي في استعلامك:

http://localhost:8080/emulator/v1/projects/<project_id>:ruleCoverage

الفروق بين المحاكي والإنتاج

  1. لا يتعين عليك إنشاء مشروع Cloud Firestore بشكل صريح. يقوم المحاكي تلقائيًا بإنشاء أي مثيل يتم الوصول إليه.
  2. لا يعمل محاكي Cloud Firestore مع تدفق مصادقة Firebase العادي. بدلا من ذلك، في Firebase اختبار SDK، قدمنا initializeTestApp() الأسلوب في rules-unit-testing المكتبة، والتي تأخذ auth المجال. سيعمل مقبض Firebase الذي تم إنشاؤه باستخدام هذه الطريقة كما لو أنه قد تمت مصادقته بنجاح ككيان تقدمه. إذا كنت تمر في null ، وسوف تتصرف كمستخدم مصادق ( auth != null ستفشل قواعد، على سبيل المثال).

استكشاف المشكلات المعروفة وإصلاحها

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

سلوك الاختبار غير متسق

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

على وجه الخصوص ، راجع العمليات غير المتزامنة التالية:

  • وضع قواعد الأمن و، على سبيل المثال، initializeTestEnvironment .
  • القراءة والكتابة البيانات، مع، على سبيل المثال، db.collection("users").doc("alice").get() .
  • تأكيدات التشغيلية، بما في ذلك assertSucceeds و assertFails .

تجتاز الاختبارات فقط في المرة الأولى التي تقوم فيها بتحميل المحاكي

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

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

إعداد الاختبار معقد للغاية

عند إعداد اختبارك ، قد ترغب في تعديل البيانات بطريقة لا تسمح بها قواعد أمان Cloud Firestore بالفعل. إذا القواعد الخاصة بك وجعل تجربة مجمع الإعداد، حاول استخدام RulesTestEnvironment.withSecurityRulesDisabled في خطوات الإعداد، بحيث يقرأ ويكتب سوف لن تؤدي PERMISSION_DENIED أخطاء.

بعد ذلك، يمكن الاختبار إجراء عمليات كمستخدم مصادقة أو مصادق باستخدام RulesTestEnvironment.authenticatedContext و unauthenticatedContext على التوالي. يتيح لك ذلك التحقق من أن قواعد أمان Cloud Firestore الخاصة بك تسمح / ترفض الحالات المختلفة بشكل صحيح.