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

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

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

• لست بحاجة إلى إنشاء مثيل قاعدة بيانات صراحةً. سينشئ المحاكي تلقائيًا أي مثيل قاعدة بيانات يتم الوصول إليه.
• يتم بدء كل قاعدة بيانات جديدة بقواعد مغلقة، لذا لن يتمكّن المستخدمون غير المشرفين من القراءة أو الكتابة.
• تطبّق كل قاعدة بيانات محاكية حدود وحصص خطة Spark (على وجه الخصوص، يحدّ هذا من كلّ مثيل بـ 100 اتصالٍ مماثل).
• ستقبل أي قاعدة بيانات السلسلة "owner" كرمز مميّز لاعتماد المشرف.
• لا تتيح أدوات المحاكاة حاليًا التفاعل مع منتجات Firebase الأخرى. يُرجى العِلم أنّ عملية مصادقة Firebase العادية لا تعمل. بدلاً من ذلك، يمكنك استخدام طريقة 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 مكتبة اختبار وحدات قواعد الأمان مع كلّ من الإصدار 9 من حزمة تطوير البرامج (SDK) لـ JavaScript والإصدار 8 من حزمة SDK. تختلف واجهات برمجة التطبيقات الخاصة بالمكتبة اختلافًا كبيرًا. ننصحك باستخدام مكتبة الاختبار في الإصدار 9، وهي أكثر سلاسة وتطلب إعدادًا أقل للاتصال بالمحاكيات، وبالتالي تجنُّب استخدام موارد الإنتاج بدون قصد. للتوافق مع الإصدارات القديمة، نواصل إتاحة مكتبة اختبار الإصدار 8.

• طرق الاختبار الشائعة ودوالّ المرافق في حزمة تطوير البرامج (SDK) من الإصدار 9
• طرق الاختبار الخاصة بالمحاكي في حزمة 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.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()

يمكنك تنفيذ دالة إعداد اختبار باستخدام سياق يعمل كما لو كانت قواعد الأمان متوقفة.

تأخذ هذه الطريقة دالة ردّ اتصال تستخدِم سياق Security-Rules-bypassing وتُعرِض عملية غير مكتملة. سيتمّ إتلاف السياق بعد حلّ الوعد أو رفضه.

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) لإصدار v8 من 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());

واجهة برمجة تطبيقات مكتبة RUT لحزمة JS SDK الإصدار 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());