اختبارات الوحدة الإعلانية

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

Firebase Local Emulator Suite تسهّل هذه الأداة التحقّق الكامل من ميزات تطبيقك وسلوكه. وهي أيضًا أداة رائعة للتحقّق من إعدادات Firebase Security Rules. استخدِم محاكيات Firebase لتشغيل اختبارات الوحدات وأتمتتها في بيئة محلية. من المفترض أن تساعدك الطرق الموضّحة في هذا المستند في إنشاء اختبارات الوحدات وبرمجتها تلقائيًا لتطبيقك، وهي اختبارات تتحقّق من صحة Rules.

إذا لم يسبق لك إجراء ذلك، أعِدّ محاكيات Firebase.

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

قبل البدء في استخدام المحاكي، يُرجى مراعاة ما يلي:

• سيحمّل المحاكي في البداية القواعد المحدّدة في الحقل firestore.rules أو الحقل storage.rules في ملف firebase.json. إذا لم يكن الملف متوفّرًا ولم تستخدم الطريقتَين loadFirestoreRules أو loadStorageRules الموضّحتَين أدناه، سيتعامل المحاكي مع جميع المشاريع على أنّها تتضمّن قواعد مفتوحة.
• في حين أنّ معظم حِزم تطوير البرامج (SDK) من Firebase تعمل مع المحاكيات مباشرةً، لا تتوافق مكتبة @firebase/rules-unit-testing إلا مع authالمحاكاةauth في "قواعد الأمان"، ما يسهّل إجراء اختبارات الوحدات. بالإضافة إلى ذلك، تتيح المكتبة بعض الميزات الخاصة بالمحاكي، مثل محو جميع البيانات، كما هو موضّح أدناه.
• ستقبل المحاكيات أيضًا رموز Firebase Auth المميزة الخاصة بالإنتاج والمقدَّمة من خلال حِزم تطوير البرامج (SDK) الخاصة بالعملاء، وستقيّم القواعد وفقًا لذلك، ما يتيح ربط تطبيقك مباشرةً بالمحاكيات في اختبارات الدمج والاختبارات اليدوية.

الاختلافات بين محاكيات قواعد البيانات وبيئة الإنتاج

• ليس عليك إنشاء مثيل قاعدة بيانات بشكلٍ صريح. سينشئ المحاكي تلقائيًا أي مثيل قاعدة بيانات يتم الوصول إليه.
• يتم بدء تشغيل كل قاعدة بيانات جديدة بقواعد مغلقة، وبالتالي لن يتمكّن المستخدمون غير المشرفين من القراءة أو الكتابة.
• تطبِّق كل قاعدة بيانات محاكية حدود خطة Spark وحصصها (والجدير بالذكر أنّ هذا يحدّ من كل مثيل إلى 100 اتصال متزامن).
• ستقبل أي قاعدة بيانات السلسلة "owner" كرمز مميّز لمصادقة المشرف.
• لا تتضمّن المحاكيات حاليًا تفاعلات تعمل مع منتجات Firebase الأخرى. والجدير بالذكر أنّ مسار المصادقة العادي في Firebase Authentication لا يعمل. يمكنك بدلاً من ذلك استخدام طريقة initializeTestApp() في مكتبة rules-unit-testing، والتي تتضمّن حقل auth. يتصرّف عنصر Firebase الذي تم إنشاؤه باستخدام هذه الطريقة كما لو أنّه تمّت مصادقته بنجاح كأي كيان تقدّمه. إذا أدخلت null، سيتم التعامل معها كمستخدم غير مصادق عليه (لن يتم تنفيذ قواعد auth != null، على سبيل المثال).

التفاعل مع محاكي Realtime Database

يمكن الوصول إلى مثيل Realtime Database في Firebase على نطاق فرعي من firebaseio.com، ويمكنك الوصول إلى واجهة برمجة التطبيقات REST على النحو التالي:

https://<database_name>.firebaseio.com/path/to/my/data.json

يعمل المحاكي محليًا، ويمكن الوصول إليه على localhost:9000. للتفاعل مع مثيل قاعدة بيانات معيّن، عليك استخدام مَعلمة طلب البحث ns لتحديد اسم قاعدة البيانات.

http://localhost:9000/path/to/my/data.json?ns=<database_name>

إجراء اختبارات الوحدات المحلية باستخدام الإصدار 9 من حزمة تطوير البرامج (SDK) في JavaScript

توزّع Firebase مكتبة لاختبار وحدات "قواعد الأمان" مع كلّ من حزمة JavaScript SDK الإصدار 9 والإصدارات الأقدم وحزمة SDK الإصدار 8. تختلف واجهات برمجة التطبيقات الخاصة بالمكتبة بشكل كبير. ننصحك باستخدام مكتبة الاختبار الإصدار 9، لأنّها أكثر سلاسة ولا تتطلّب الكثير من الإعدادات للاتصال بالمحاكيات، وبالتالي يمكنك تجنُّب الاستخدام غير المقصود لموارد الإنتاج بأمان. لضمان التوافق مع الإصدارات القديمة، سنواصل إتاحة مكتبة الاختبار الإصدار 8.

• طُرق الاختبار الشائعة ووظائف الأداة المساعدة في الإصدار 9 من حزمة تطوير البرامج (SDK)
• طُرق الاختبار الخاصة بالمحاكي في حزمة SDK الإصدار 9

استخدِم وحدة @firebase/rules-unit-testing للتفاعل مع المحاكي الذي يتم تشغيله محليًا. إذا ظهرت لك أخطاء في المهلة أو أخطاء ECONNREFUSED، تحقَّق جيدًا من أنّ المحاكي يعمل بالفعل.

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

تدرك مكتبة اختبار الوحدات لقواعد الإصدار 9 دائمًا المحاكيات ولا تتفاعل أبدًا مع موارد الإنتاج.

يمكنك استيراد المكتبة باستخدام عبارات الاستيراد النموذجية في الإصدار 9. على سبيل المثال:

import {
  assertFails,
  assertSucceeds,
  initializeTestEnvironment
} 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
• إعداد بيانات اختبارية بدون تشغيل Rules، وذلك باستخدام طريقة ملائمة تتيح لك تجاوزها مؤقتًا، RulesTestEnvironment.withSecurityRulesDisabled
• إعداد مجموعة الاختبارات وخطافات ما قبل الاختبار وما بعده لكل اختبار من خلال طلبات لتنظيف بيانات الاختبار والبيئة، مثل RulesTestEnvironment.cleanup() أو RulesTestEnvironment.clearFirestore()
• تنفيذ حالات اختبار تحاكي حالات المصادقة باستخدام RulesTestEnvironment.authenticatedContext و RulesTestEnvironment.unauthenticatedContext

الطرق الشائعة والدوال المساعدة

يمكنك أيضًا الاطّلاع على طُرق الاختبار الخاصة بالمحاكي باستخدام واجهة برمجة التطبيقات النموذجية.

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، الذي يتصرف مثل مستخدم Authentication تمت المصادقة عليه. ستتضمّن الطلبات التي تم إنشاؤها من خلال السياق الذي تم عرضه رمزًا مميزًا وهميًا Authentication. يمكنك اختياريًا تمرير عنصر يحدّد المطالبات المخصّصة أو عمليات الإلغاء لحمولات الرموز المميزة Authentication.

استخدِم عنصر سياق الاختبار الذي تم عرضه في اختباراتك للوصول إلى أي مثيلات محاكي تم إعدادها، بما في ذلك تلك التي تم إعدادها باستخدام 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، الذي يعمل كعميل لم يتم تسجيل الدخول إليه من خلال Authentication. لن تتضمّن الطلبات التي يتم إنشاؤها من خلال السياق الذي تم عرضه رموزًا مميّزة خاصة بخدمة 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>

هذه دالة مساعدة لحالات الاختبار.

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

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

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

هذه دالة مساعدة لحالات الاختبار.

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

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

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

يمكنك أيضًا الاطّلاع على طُرق الاختبار الشائعة ووظائف الأداة المساعدة باستخدام واجهة برمجة التطبيقات النموذجية.

إجراء اختبارات الوحدات المحلية باستخدام حزمة تطوير البرامج (SDK) المستندة إلى JavaScript الإصدار 8

اختَر منتجًا للاطّلاع على الطرق التي تستخدمها حزمة تطوير البرامج (SDK) لاختبار Firebase للتفاعل مع المحاكي.

firebase.initializeTestApp({
  projectId: "my-test-project",
  auth: { uid: "alice", email: "alice@example.com" }
});

firebase.initializeAdminApp({ projectId: "my-test-project" });
    

Promise.all(firebase.apps().map(app => app.delete()))

firebase.loadFirestoreRules({
  projectId: "my-test-project",
  rules: fs.readFileSync("/path/to/firestore.rules", "utf8")
});
    

firebase.assertFails(app.firestore().collection("private").doc("super-secret-document").get());
    

firebase.assertSucceeds(app.firestore().collection("public").doc("test-document").get());
    

firebase.clearFirestoreData({
  projectId: "my-test-project"
});
   

firebase.initializeTestApp({
  databaseName: "my-database",
  auth: { uid: "alice" }
});

firebase.initializeAdminApp({ databaseName: "my-database" });

firebase
      .loadDatabaseRules({
        databaseName: "my-database",
        rules: "{'rules': {'.read': false, '.write': false}}"
      });

 Promise.all(firebase.apps().map(app => app.delete()))

firebase.assertFails(app.database().ref("secret").once("value"));

firebase.assertSucceeds(app.database().ref("public").once("value"));

firebase.initializeTestApp({
  storageBucket: "my-bucket",
  auth: { uid: "alice" }
});

firebase.initializeAdminApp({ storageBucket: "my-bucket" });

firebase
      .loadStorageRules({
        storageBucket: "my-bucket",
        rules: fs.readFileSync("/path/to/storage.rules", "utf8")
      });

 Promise.all(firebase.apps().map(app => app.delete()))

firebase.assertFails(app.storage().ref("letters/private.doc").getMetadata());

firebase.assertFails(app.storage().ref("images/cat.png").getMetadata());

واجهة برمجة تطبيقات مكتبة RUT للإصدار 8 من حزمة تطوير البرامج (SDK) بلغة JavaScript

اختَر منتجًا للاطّلاع على الطرق التي تستخدمها حزمة تطوير البرامج (SDK) لاختبار Firebase للتفاعل مع المحاكي.

firebase.initializeTestApp({
  projectId: "my-test-project",
  auth: { uid: "alice", email: "alice@example.com" }
});

firebase.initializeAdminApp({ projectId: "my-test-project" });
    

Promise.all(firebase.apps().map(app => app.delete()))

firebase.loadFirestoreRules({
  projectId: "my-test-project",
  rules: fs.readFileSync("/path/to/firestore.rules", "utf8")
});
    

firebase.assertFails(app.firestore().collection("private").doc("super-secret-document").get());
    

firebase.assertSucceeds(app.firestore().collection("public").doc("test-document").get());
    

firebase.clearFirestoreData({
  projectId: "my-test-project"
});
   

firebase.initializeTestApp({
  databaseName: "my-database",
  auth: { uid: "alice" }
});

firebase.initializeAdminApp({ databaseName: "my-database" });

firebase
      .loadDatabaseRules({
        databaseName: "my-database",
        rules: "{'rules': {'.read': false, '.write': false}}"
      });

 Promise.all(firebase.apps().map(app => app.delete()))

firebase.assertFails(app.database().ref("secret").once("value"));

firebase.assertSucceeds(app.database().ref("public").once("value"));

firebase.initializeTestApp({
  storageBucket: "my-bucket",
  auth: { uid: "alice" }
});

firebase.initializeAdminApp({ storageBucket: "my-bucket" });

firebase
      .loadStorageRules({
        storageBucket: "my-bucket",
        rules: fs.readFileSync("/path/to/storage.rules", "utf8")
      });

 Promise.all(firebase.apps().map(app => app.delete()))

firebase.assertFails(app.storage().ref("letters/private.doc").getMetadata());

firebase.assertFails(app.storage().ref("images/cat.png").getMetadata());