تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تطوير محلي باستخدام "حزمة محاكي Firebase"

1- قبل البدء

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

المتطلبات الأساسية

أداة تحرير بسيطة مثل Visual Studio Code أو Atom أو Sublime Text
Node.js 10.0.0 أو إصدار أحدث (لتثبيت Node.js، استخدم nvm، للتحقق من الإصدار، شغِّل node --version)
Java 7 أو إصدار أحدث (لتثبيت Java، يُرجى استخدام هذه التعليمات، أو تشغيل java -version للتحقّق من الإصدار)

الأنشطة

في هذا الدرس التطبيقي حول الترميز، سيتم تشغيل تطبيق بسيط للتسوّق على الإنترنت وتصحيح الأخطاء فيه بدعم من خدمات متعدّدة في Firebase:

Cloud Firestore: وهي قاعدة بيانات NoSQL قابلة للتوسّع على مستوى العالم وبدون خوادم ولديها إمكانيات الوقت الفعلي.
وظائف السحابة الإلكترونية: رمز واجهة خلفية بدون خادم يتم تشغيله استجابةً للأحداث أو طلبات HTTP.
مصادقة Firebase: خدمة مصادقة مُدارة تندمج مع منتجات Firebase الأخرى.
استضافة Firebase: استضافة سريعة وآمنة لتطبيقات الويب

ستربط التطبيق بحزمة Emulator Suite لتفعيل عمليات التطوير المحلية.

ستتعلم أيضًا كيفية:

كيفية ربط تطبيقك بـ "مجموعة أدوات المحاكاة" وكيفية ربط أدوات المحاكاة المختلفة ببعضها.
آلية عمل "قواعد أمان Firebase" وكيفية اختبار قواعد أمان Firestore باستخدام محاكي محلي
كيفية كتابة دالة Firebase التي يتم تشغيلها بواسطة أحداث Firestore وكيفية كتابة اختبارات التكامل التي يتم تشغيلها مقابل Emulator Suite.

2- إعداد

الحصول على رمز المصدر

في هذا الدرس التطبيقي حول الترميز، ستبدأ بإصدار من عيّنة The Fire Store أوشكت على اكتماله، لذا عليك أولاً استنساخ رمز المصدر:

$ git clone https://github.com/firebase/emulators-codelab.git

بعد ذلك، انتقِل إلى دليل الدرس التطبيقي حول الترميز، حيث ستعمل خلال باقي هذا الدرس التطبيقي:

$ cd emulators-codelab/codelab-initial-state

الآن، قم بتثبيت التبعيات حتى تتمكن من تشغيل التعليمة البرمجية. وإذا كان اتصال الإنترنت بطيئًا، قد يستغرق ذلك دقيقة أو اثنتين:

# Move into the functions directory
$ cd functions

# Install dependencies
$ npm install

# Move back into the previous directory
$ cd ../

الحصول على واجهة سطر الأوامر في Firebase

تعتبر مجموعة أدوات المحاكاة جزءًا من واجهة سطر الأوامر في Firebase (واجهة سطر الأوامر) والتي يمكن تثبيتها على جهازك باستخدام الأمر التالي:

$ npm install -g firebase-tools

بعد ذلك، تأكَّد من استخدام أحدث إصدار من واجهة سطر الأوامر. من المفترض أن يعمل هذا الدرس التطبيقي مع الإصدار 9.0.0 أو الإصدارات الأحدث، ولكنّ الإصدارات الأحدث تتضمّن المزيد من إصلاحات الأخطاء.

$ firebase --version
9.6.0

الربط بمشروعك على Firebase

إذا لم يكن لديك مشروع على Firebase، أنشئ مشروع Firebase جديدًا في وحدة تحكُّم Firebase. دوِّن رقم تعريف المشروع الذي تختاره، ستحتاج إليه لاحقًا.

نحتاج الآن إلى ربط هذا الرمز بمشروعك في Firebase. شغِّل الأمر التالي أولاً لتسجيل الدخول إلى واجهة سطر الأوامر في Firebase:

$ firebase login

بعد ذلك، شغِّل الأمر التالي لإنشاء اسم مستعار للمشروع. استبدِل $YOUR_PROJECT_ID برقم تعريف مشروعك على Firebase.

$ firebase use $YOUR_PROJECT_ID

أنت الآن جاهز لتشغيل التطبيق!

3- تشغيل أدوات المحاكاة

في هذا القسم، ستُشغِّل التطبيق محليًا. وهذا يعني أن الوقت قد حان لبدء تشغيل مجموعة أدوات المحاكاة.

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

من داخل دليل مصدر درس تطبيقي حول الترميز، شغِّل الأمر التالي لبدء أدوات المحاكاة:

$ firebase emulators:start --import=./seed

من المفترض أن تظهر لك نتائج على النحو التالي:

$ firebase emulators:start --import=./seed
i  emulators: Starting emulators: auth, functions, firestore, hosting
⚠  functions: The following emulators are not running, calls to these services from the Functions emulator will affect production: database, pubsub
i  firestore: Importing data from /Users/samstern/Projects/emulators-codelab/codelab-initial-state/seed/firestore_export/firestore_export.overall_export_metadata
i  firestore: Firestore Emulator logging to firestore-debug.log
i  hosting: Serving hosting files from: public
✔  hosting: Local server: http://127.0.0.1:5000
i  ui: Emulator UI logging to ui-debug.log
i  functions: Watching "/Users/samstern/Projects/emulators-codelab/codelab-initial-state/functions" for Cloud Functions...
✔  functions[calculateCart]: firestore function initialized.

┌─────────────────────────────────────────────────────────────┐
│ ✔  All emulators ready! It is now safe to connect your app. │
│ i  View Emulator UI at http://127.0.0.1:4000                │
└─────────────────────────────────────────────────────────────┘

┌────────────────┬────────────────┬─────────────────────────────────┐
│ Emulator       │ Host:Port      │ View in Emulator UI             │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Authentication │ 127.0.0.1:9099 │ http://127.0.0.1:4000/auth      │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Functions      │ 127.0.0.1:5001 │ http://127.0.0.1:4000/functions │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Firestore      │ 127.0.0.1:8080 │ http://127.0.0.1:4000/firestore │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Hosting        │ 127.0.0.1:5000 │ n/a                             │
└────────────────┴────────────────┴─────────────────────────────────┘
  Emulator Hub running at 127.0.0.1:4400
  Other reserved ports: 4500

Issues? Report them at https://github.com/firebase/firebase-tools/issues and attach the *-debug.log files.

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

ربط تطبيق الويب بالمحاكيات

استنادًا إلى الجدول الوارد في السجلّات، يمكننا ملاحظة أنّ محاكي Cloud Firestore يستخدم المنفذ 8080 وأنّ محاكي المصادقة يستمع إلى بيانات المنفذ 9099.

┌────────────────┬────────────────┬─────────────────────────────────┐
│ Emulator       │ Host:Port      │ View in Emulator UI             │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Authentication │ 127.0.0.1:9099 │ http://127.0.0.1:4000/auth      │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Functions      │ 127.0.0.1:5001 │ http://127.0.0.1:4000/functions │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Firestore      │ 127.0.0.1:8080 │ http://127.0.0.1:4000/firestore │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Hosting        │ 127.0.0.1:5000 │ n/a                             │
└────────────────┴────────────────┴─────────────────────────────────┘

لنربط رمز الواجهة الأمامية بالمحاكي بدلاً من الإصدار العلني. افتح ملف public/js/homepage.js وابحث عن الدالة onDocumentReady. يتبيّن لنا أنّ الرمز يصل إلى نسختَي Firestore وAuth العادية:

public/js/homepage.js

  const auth = firebaseApp.auth();
  const db = firebaseApp.firestore();

يجب تعديل العنصرَين db وauth للإشارة إلى أدوات المحاكاة المحلية:

public/js/homepage.js

  const auth = firebaseApp.auth();
  const db = firebaseApp.firestore();

  // ADD THESE LINES
  if (location.hostname === "127.0.0.1") {
    console.log("127.0.0.1 detected!");
    auth.useEmulator("http://127.0.0.1:9099");
    db.useEmulator("127.0.0.1", 8080);
  }

وعندما يعمل التطبيق على جهازك المحلي (الذي يتيحه محاكي الاستضافة)، يشير عميل Firestore أيضًا إلى المحاكي المحلي بدلاً من قاعدة بيانات الإنتاج.

فتح واجهة EmulatorUI

في متصفح الويب، انتقل إلى http://127.0.0.1:4000/. من المفترض أن تظهر لك واجهة مستخدم Emulator Suite.

الشاشة الرئيسية لواجهة مستخدم أدوات المحاكاة

انقر لعرض واجهة المستخدم لمحاكي Firestore. تحتوي مجموعة items على بيانات بسبب البيانات التي تم استيرادها باستخدام العلامة --import.

4. تشغيل التطبيق

فتح التطبيق

في متصفح الويب، انتقل إلى http://127.0.0.1:5000 وسيظهر لك تطبيق Fire Store قيد التشغيل محليًا على جهازك.

استخدام التطبيق

اختَر سلعة من الصفحة الرئيسية وانقر على إضافة إلى سلة التسوّق. للأسف، سيحدث الخطأ التالي:

لنصلح هذا الخطأ. ولأنّ كل شيء يعمل في المحاكيات، يمكننا إجراء التجارب بدون القلق بشأن التأثير في البيانات الحقيقية.

5- تصحيح أخطاء التطبيق

العثور على الخطأ

حسنًا، لنلقِ نظرة على "وحدة تحكّم المطوّرين" في Chrome. اضغط على Control+Shift+J (Windows أو Linux أو Chrome) أو Command+Option+J (Mac) للاطّلاع على الخطأ في وحدة التحكّم:

يبدو أنّه حدث خطأ في طريقة addToCart. لنلقِ نظرة على ذلك. أين نحاول الوصول إلى شيء يسمى uid بهذه الطريقة ولماذا يكون null؟ في الوقت الحالي، تظهر الطريقة على النحو التالي في public/js/homepage.js:

public/js/homepage.js

  addToCart(id, itemData) {
    console.log("addToCart", id, JSON.stringify(itemData));
    return this.db
      .collection("carts")
      .doc(this.auth.currentUser.uid)
      .collection("items")
      .doc(id)
      .set(itemData);
  }

حقًا! لم يتم تسجيل الدخول إلى التطبيق. وفقًا لمستندات مصادقة Firebase، عندما لا نسجل الدخول، يكون auth.currentUser null. لنقم بإضافة تحقق لذلك:

public/js/homepage.js

  addToCart(id, itemData) {
    // ADD THESE LINES
    if (this.auth.currentUser === null) {
      this.showError("You must be signed in!");
      return;
    }

    // ...
  }

اختبار التطبيق

الآن، يمكنك إعادة تحميل الصفحة ثم النقر على إضافة إلى سلة التسوّق. من المفترض أن يظهر لك خطأ أكثر وضوحًا هذه المرة:

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

ومع ذلك، لا تبدو الأرقام صحيحة على الإطلاق:

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

6- عوامل تشغيل الدوال المحلية

يؤدي النقر على إضافة إلى سلة التسوّق إلى بدء سلسلة من الأحداث التي تتضمّن أدوات محاكاة متعددة. في سجلات واجهة سطر الأوامر في Firebase، من المفترض أن تظهر لك رسائل مثل الرسائل التالية بعد إضافة عنصر إلى سلة التسوق:

i  functions: Beginning execution of "calculateCart"
i  functions: Finished "calculateCart" in ~1s

وقد حدثت أربعة أحداث رئيسية لإنتاج هذه السجلّات وتحديث واجهة المستخدم الذي لاحظته:

1) الكتابة في Firestore - العميل

تمت إضافة مستند جديد إلى مجموعة Firestore /carts/{cartId}/items/{itemId}/. يمكنك رؤية هذا الرمز في الدالة addToCart داخل public/js/homepage.js:

public/js/homepage.js

  addToCart(id, itemData) {
    // ...
    console.log("addToCart", id, JSON.stringify(itemData));
    return this.db
      .collection("carts")
      .doc(this.auth.currentUser.uid)
      .collection("items")
      .doc(id)
      .set(itemData);
  }

2) تفعيل وظيفة السحابة الإلكترونية

ترصد دالة السحابة الإلكترونية calculateCart أي أحداث كتابة (إنشاء أو تعديل أو حذف) تحدث لعناصر سلة التسوّق باستخدام المشغِّل onWrite، الذي يمكنك الاطّلاع عليه في functions/index.js:

Functions/index.js

exports.calculateCart = functions.firestore
    .document("carts/{cartId}/items/{itemId}")
    .onWrite(async (change, context) => {
      try {
        let totalPrice = 125.98;
        let itemCount = 8;

        const cartRef = db.collection("carts").doc(context.params.cartId);

        await cartRef.update({
          totalPrice,
          itemCount
        });
      } catch(err) {
      }
    }
);

3) الكتابة في Firestore - المشرف

تقرأ الدالة calculateCart كل السلع المضمّنة في سلة التسوّق وتضيف إجمالي الكمية والسعر، ثم تعدّل "سلّة التسوّق". المستند الذي يحتوي على القيم الإجمالية الجديدة (راجِع cartRef.update(...) أعلاه).

4) قراءة Firestore - العميل

تم الاشتراك في الواجهة الأمامية للويب لتلقي تحديثات حول التغييرات التي طرأت على سلة التسوق. ويتم تعديلها في الوقت الفعلي بعد أن تكتب دالّة السحابة الإلكترونية القيم الإجمالية الجديدة وتعدِّل واجهة المستخدم، كما يظهر في public/js/homepage.js:

public/js/homepage.js

this.cartUnsub = cartRef.onSnapshot(cart => {
   // The cart document was changed, update the UI
   // ...
});

الملخّص

أحسنت. لقد أعددت للتو تطبيقًا محليًا بالكامل يستخدم ثلاثة أدوات محاكاة مختلفة لمنصة Firebase لإجراء الاختبار المحلي بالكامل.

انتظر، فهناك المزيد. في القسم التالي، ستتعرّف على المعلومات التالية:

طريقة كتابة اختبارات الوحدات التي تستخدم "محاكيات Firebase"
كيفية استخدام "محاكيات Firebase" لتصحيح أخطاء "قواعد الأمان"

7- إنشاء قواعد أمان مخصَّصة لتطبيقك

يقرأ تطبيق الويب البيانات ويكتبها، ولكننا لم نقلق بشأن الأمان على الإطلاق. تستخدم Cloud Firestore نظامًا يُسمى "قواعد الأمان" للإعلان عن من لديه حق الوصول لقراءة البيانات وكتابتها. تعتبر مجموعة أدوات المحاكاة وسيلة رائعة لوضع هذه القواعد الأولية.

في المحرِّر، افتح الملف "emulators-codelab/codelab-initial-state/firestore.rules". سترى أن لدينا ثلاثة أقسام رئيسية في القواعد:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // User's cart metadata
    match /carts/{cartID} {
      // TODO: Change these! Anyone can read or write.
      allow read, write: if true;
    }

    // Items inside the user's cart
    match /carts/{cartID}/items/{itemID} {
      // TODO: Change these! Anyone can read or write.
      allow read, write: if true;
    }

    // All items available in the store. Users can read
    // items but never write them.
    match /items/{itemID} {
      allow read: if true;
    }
  }
}

في الوقت الحالي يمكن لأي شخص قراءة البيانات وكتابتها في قاعدة البيانات الخاصة بنا! نريد أن نضمن عدم نجاح سوى العمليات الصالحة ومن عدم تسريب أي معلومات حساسة.

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

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // User's cart metadata
    match /carts/{cartID} {
      // UPDATE THIS LINE
      allow read, write: if false;
    }

    // Items inside the user's cart
    match /carts/{cartID}/items/{itemID} {
      // UPDATE THIS LINE
      allow read, write: if false;
    }

    // All items available in the store. Users can read
    // items but never write them.
    match /items/{itemID} {
      allow read: if true;
    }
  }
}

8- تشغيل أدوات المحاكاة والاختبارات

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

في سطر الأوامر، تأكَّد من أنّك في emulators-codelab/codelab-initial-state/. قد تظل المحاكيات قيد التشغيل من الخطوات السابقة. إذا لم يكن الأمر كذلك، فيمكنك بدء تشغيل أدوات المحاكاة مرة أخرى:

$ firebase emulators:start --import=./seed

وبعد تشغيل أدوات المحاكاة، يمكنك إجراء اختبارات محليًا عليها.

إجراء الاختبارات

في سطر الأوامر في علامة تبويب جديدة الطرفية من الدليل emulators-codelab/codelab-initial-state/

ننتقل أولاً إلى دليل الدوال (سنبقى هنا لبقية الدرس التطبيقي حول الترميز):

$ cd functions

شغِّل الآن اختبارات Mocha في دليل الدوال، ثم انتقِل إلى أعلى الناتج:

# Run the tests
$ npm test

> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha

  shopping carts
    1) can be created and updated by the cart owner
    2) can be read only by the cart owner

  shopping cart items
    3) can be read only by the cart owner
    4) can be added only by the cart owner

  adding an item to the cart recalculates the cart total. 
    - should sum the cost of their items


  0 passing (364ms)
  1 pending
  4 failing

والآن لدينا أربعة إخفاقات. أثناء إنشاء ملف القواعد، يمكنك قياس مستوى التقدّم من خلال مشاهدة المزيد من الاختبارات التي تم اجتيازها.

9- الوصول الآمن إلى سلة التسوّق

أول إخفاقين هما "سلة التسوق" التي تختبر ما يلي:

يمكن للمستخدمين إنشاء سلّات التسوّق الخاصة بهم وتعديلها فقط.
يمكن للمستخدمين قراءة سلّات التسوّق الخاصة بهم فقط.

الدوال/test.js

  it('can be created and updated by the cart owner', async () => {
    // Alice can create her own cart
    await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart").set({
      ownerUID: "alice",
      total: 0
    }));

    // Bob can't create Alice's cart
    await firebase.assertFails(bobDb.doc("carts/alicesCart").set({
      ownerUID: "alice",
      total: 0
    }));

    // Alice can update her own cart with a new total
    await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart").update({
      total: 1
    }));

    // Bob can't update Alice's cart with a new total
    await firebase.assertFails(bobDb.doc("carts/alicesCart").update({
      total: 1
    }));
  });

  it("can be read only by the cart owner", async () => {
    // Setup: Create Alice's cart as admin
    await admin.doc("carts/alicesCart").set({
      ownerUID: "alice",
      total: 0
    });

    // Alice can read her own cart
    await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart").get());

    // Bob can't read Alice's cart
    await firebase.assertFails(bobDb.doc("carts/alicesCart").get());
  });

لنجتاز هذه الاختبارات. في المحرِّر، افتح ملف قواعد الأمان firestore.rules وعدِّل العبارات ضمن match /carts/{cartID}:

firestore.rules

rules_version = '2';
service cloud.firestore {
    // UPDATE THESE LINES
    match /carts/{cartID} {
      allow create: if request.auth.uid == request.resource.data.ownerUID;
      allow read, update, delete: if request.auth.uid == resource.data.ownerUID;
    }

    // ...
  }
}

تتيح هذه القواعد الآن لمالك سلة التسوّق إمكانية الوصول للقراءة والكتابة فقط.

للتحقّق من البيانات الواردة ومصادقة المستخدم، نستخدم عنصرَين متاحَين في سياق كل قاعدة:

يحتوي العنصر request على بيانات وبيانات وصفية عن العملية التي تتم محاولة تنفيذها.
إذا كان مشروع Firebase يستخدم مصادقة Firebase، يصف العنصر request.auth المستخدم الذي يقدّم الطلب.

10- اختبار الوصول إلى سلة التسوّق

تعدّل "حزمة المحاكيات" القواعد تلقائيًا كلما تم حفظ firestore.rules. يمكنك التأكد من أنّ المحاكي عدّل القواعد من خلال البحث في علامة التبويب التي تشغّل المحاكي للرسالة Rules updated:

أعد تشغيل الاختبارات، وتأكد من اجتياز أول اختبارين الآن:

$ npm test

> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha

  shopping carts
    ✓ can be created and updated by the cart owner (195ms)
    ✓ can be read only by the cart owner (136ms)

  shopping cart items
    1) can be read only by the cart owner
    2) can be added only by the cart owner

  adding an item to the cart recalculates the cart total. 
    - should sum the cost of their items

  2 passing (482ms)
  1 pending
  2 failing

أحسنت! أصبحت الآن آمنًا للوصول إلى سلات التسوّق. لننتقل إلى الاختبار التالي الذي أخفق.

11- التحقّق من "إضافة إلى عربة التسوق" التدفق في واجهة المستخدم

في الوقت الحالي، على الرغم من أن مالكي سلة التسوق يقرأون ويكتبون في سلة التسوق، إلا أنهم لا يمكنهم قراءة عناصر فردية في سلة التسوق أو كتابتها. ويرجع ذلك إلى أنّه بينما يمكن للمالكين الوصول إلى مستند سلة التسوّق، لا يمكنهم الوصول إلى المجموعة الفرعية للسلع في سلة التسوّق.

هذه حالة معطّلة للمستخدمين.

ارجع إلى واجهة مستخدم الويب التي تعمل على http://127.0.0.1:5000, وحاول إضافة سلعة إلى سلة التسوق. يظهر لك الخطأ Permission Denied، ويظهر لك في وحدة تحكُّم تصحيح الأخطاء، لأنّنا لم نمنح المستخدمين بعد إذن الوصول إلى المستندات التي تم إنشاؤها في المجموعة الفرعية items.

12- السماح بالوصول إلى عناصر سلة التسوّق

يؤكّد هذان الاختباران أنّه يمكن للمستخدمين إضافة سلع أو قراءتها من سلة التسوّق فقط:

  it("can be read only by the cart owner", async () => {
    // Alice can read items in her own cart
    await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart/items/milk").get());

    // Bob can't read items in alice's cart
    await firebase.assertFails(bobDb.doc("carts/alicesCart/items/milk").get())
  });

  it("can be added only by the cart owner",  async () => {
    // Alice can add an item to her own cart
    await firebase.assertSucceeds(aliceDb.doc("carts/alicesCart/items/lemon").set({
      name: "lemon",
      price: 0.99
    }));

    // Bob can't add an item to alice's cart
    await firebase.assertFails(bobDb.doc("carts/alicesCart/items/lemon").set({
      name: "lemon",
      price: 0.99
    }));
  });

لذا، يمكننا كتابة قاعدة تسمح بالوصول إذا كان المستخدم الحالي لديه نفس المعرف الفريد مثل المالكUID في مستند سلة التسوق. نظرًا لعدم الحاجة إلى تحديد قواعد مختلفة لـ create, update, delete، يمكنك استخدام قاعدة write التي تنطبق على جميع الطلبات التي تعدِّل البيانات.

عدِّل قاعدة المستندات في المجموعة الفرعية للعناصر. تقرأ السمة get في الشرطية قيمة من Firestore، وهي في هذه الحالة ownerUID على مستند سلة التسوّق.

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // ...

    // UPDATE THESE LINES
    match /carts/{cartID}/items/{itemID} {
      allow read, write: if get(/databases/$(database)/documents/carts/$(cartID)).data.ownerUID == request.auth.uid;
    }

    // ...
  }
}

13- اختبار الوصول إلى عناصر سلة التسوّق

يمكننا الآن إعادة إجراء الاختبار. انتقِل إلى أعلى النتيجة وتحقَّق من اجتياز المزيد من الاختبارات:

$ npm test

> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha

  shopping carts
    ✓ can be created and updated by the cart owner (195ms)
    ✓ can be read only by the cart owner (136ms)

  shopping cart items
    ✓ can be read only by the cart owner (111ms)
    ✓ can be added only by the cart owner


  adding an item to the cart recalculates the cart total. 
    - should sum the cost of their items


  4 passing (401ms)
  1 pending

أحسنت. الآن اجتزت جميع اختباراتنا. لدينا اختبار واحد في انتظار المراجعة، ولكنّنا سنصل إليه بعد بضع خطوات.

14- التحقّق من خيار "إضافة إلى عربة التسوق" التدفق مرة أخرى

ارجع إلى الواجهة الأمامية للويب ( http://127.0.0.1:5000) وأضف عنصرًا إلى سلة التسوق. هذه خطوة مهمة للتأكّد من توافق اختباراتنا وقواعدنا مع الوظائف التي يطلبها العميل. (تذكّر أنه في المرة الأخيرة التي جربنا فيها مستخدمي واجهة المستخدم لم يتمكنوا من إضافة عناصر إلى سلة التسوق!)

ويعيد البرنامج تحميل القواعد تلقائيًا عند حفظ firestore.rules. لذا، حاول إضافة شيء ما إلى عربة التسوق.

الملخّص

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

ولكن انتظر هناك المزيد!

إذا تابعت، فستتعلم ما يلي:

كيفية كتابة دالة تم تشغيلها بواسطة حدث Firestore
كيفية إنشاء اختبارات تعمل على عدة محاكيات

15- إعداد اختبارات Cloud Functions

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

تُسهل مجموعة أدوات المحاكاة اختبار وظائف السحابة الإلكترونية، حتى الوظائف التي تستخدم Cloud Firestore وغيرها من الخدمات.

في المحرِّر، افتح ملف emulators-codelab/codelab-initial-state/functions/test.js وانتقِل إلى الاختبار الأخير في الملف. وُضعت في الوقت الحالي علامة "في انتظار المراجعة":

//  REMOVE .skip FROM THIS LINE
describe.skip("adding an item to the cart recalculates the cart total. ", () => {
  // ...

  it("should sum the cost of their items", async () => {
    ...
  });
});

لتفعيل الاختبار، يجب إزالة .skip لكي يظهر على النحو التالي:

describe("adding an item to the cart recalculates the cart total. ", () => {
  // ...

  it("should sum the cost of their items", async () => {
    ...
  });
});

بعد ذلك، ابحث عن المتغيّر REAL_FIREBASE_PROJECT_ID في أعلى الملف وغيِّره إلى رقم تعريف مشروع Firebase الحقيقي.

// CHANGE THIS LINE
const REAL_FIREBASE_PROJECT_ID = "changeme";

إذا نسيت رقم تعريف مشروعك، يمكنك العثور على رقم تعريف مشروع Firebase في "إعدادات المشروع" في "وحدة تحكُّم Firebase":

16- الاطّلاع على اختبارات الدوال

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

إنشاء سلة تسوّق

تعمل Cloud Functions في بيئة خادم موثوق بها، ويمكنها استخدام مصادقة حساب الخدمة التي تستخدمها حزمة SDK للمشرف . عليك أولاً إعداد تطبيق باستخدام initializeAdminApp بدلاً من initializeApp. بعد ذلك، يمكنك إنشاء DocumentReference لسلة التسوق التي سنضيف عناصر إليها وتهيئ سلة التسوق:

it("should sum the cost of their items", async () => {
    const db = firebase
        .initializeAdminApp({ projectId: REAL_FIREBASE_PROJECT_ID })
        .firestore();

    // Setup: Initialize cart
    const aliceCartRef = db.doc("carts/alice")
    await aliceCartRef.set({ ownerUID: "alice", totalPrice: 0 });

    ...
  });

تشغيل الدالة

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

it("should sum the cost of their items", async () => {
    const db = firebase
        .initializeAdminApp({ projectId: REAL_FIREBASE_PROJECT_ID })
        .firestore();

    // Setup: Initialize cart
    const aliceCartRef = db.doc("carts/alice")
    await aliceCartRef.set({ ownerUID: "alice", totalPrice: 0 });

    //  Trigger calculateCart by adding items to the cart
    const aliceItemsRef = aliceCartRef.collection("items");
    await aliceItemsRef.doc("doc1").set({name: "nectarine", price: 2.99});
    await aliceItemsRef.doc("doc2").set({ name: "grapefruit", price: 6.99 });

    ...
    });
  });

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

استخدِم onSnapshot() لتسجيل أداة استماع لأي تغييرات في مستند سلة التسوق. تعرض onSnapshot() دالة يمكنك استدعاؤها لإلغاء تسجيل المستمع.

بالنسبة لهذا الاختبار، أضف عنصرين بتكلفة معًا 9.98 دولار. بعد ذلك، تحقَّق مما إذا كانت سلة التسوّق تحتوي على قيمتَي itemCount وtotalPrice المتوقّعتَين. إذا كان الأمر كذلك، فهذا يعني أن الدالة تؤدي وظيفتها.

it("should sum the cost of their items", (done) => {
    const db = firebase
        .initializeAdminApp({ projectId: REAL_FIREBASE_PROJECT_ID })
        .firestore();

    // Setup: Initialize cart
    const aliceCartRef = db.doc("carts/alice")
    aliceCartRef.set({ ownerUID: "alice", totalPrice: 0 });

    //  Trigger calculateCart by adding items to the cart
    const aliceItemsRef = aliceCartRef.collection("items");
    aliceItemsRef.doc("doc1").set({name: "nectarine", price: 2.99});
    aliceItemsRef.doc("doc2").set({ name: "grapefruit", price: 6.99 });
    
    // Listen for every update to the cart. Every time an item is added to
    // the cart's subcollection of items, the function updates `totalPrice`
    // and `itemCount` attributes on the cart.
    // Returns a function that can be called to unsubscribe the listener.
    await new Promise((resolve) => {
      const unsubscribe = aliceCartRef.onSnapshot(snap => {
        // If the function worked, these will be cart's final attributes.
        const expectedCount = 2;
        const expectedTotal = 9.98;
  
        // When the `itemCount`and `totalPrice` match the expectations for the
        // two items added, the promise resolves, and the test passes.
        if (snap.data().itemCount === expectedCount && snap.data().totalPrice == expectedTotal) {
          // Call the function returned by `onSnapshot` to unsubscribe from updates
          unsubscribe();
          resolve();
        };
      });
    });
   });
 });

17- إجراء الاختبارات

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

$ firebase emulators:start --import=./seed

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

$ cd functions

عند إجراء اختبارات الوحدة، من المفترض أن يظهر لك 5 اختبارات إجمالاً:

$ npm test

> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha

  shopping cart creation
    ✓ can be created by the cart owner (82ms)

  shopping cart reads, updates, and deletes
    ✓ cart can be read by the cart owner (42ms)

  shopping cart items
    ✓ items can be read by the cart owner (40ms)
    ✓ items can be added by the cart owner

  adding an item to the cart recalculates the cart total. 
    1) should sum the cost of their items

  4 passing (2s)
  1 failing

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

18- كتابة دالة

لحلّ هذا الاختبار، عليك تعديل الدالة في functions/index.js. بعض هذه الدالة مكتوبة، إلا أنها ليست كاملة. إليك الشكل الذي تظهر به الدالة حاليًا:

// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
    .firestore.document("carts/{cartId}/items/{itemId}")
    .onWrite(async (change, context) => {
      console.log(`onWrite: ${change.after.ref.path}`);
      if (!change.after.exists) {
        // Ignore deletes
        return;
      }

      let totalPrice = 125.98;
      let itemCount = 8;
      try {
        
        const cartRef = db.collection("carts").doc(context.params.cartId);

        await cartRef.update({
          totalPrice,
          itemCount
        });
      } catch(err) {
      }
    });

تضبط الدالة مرجع سلة التسوّق بشكل صحيح، ولكن بدلاً من احتساب قيمتَي totalPrice وitemCount، يتم تعديلهما إلى قيم تم ترميزها بشكل ثابت.

الجلب والتكرار من خلال

items مجموعة فرعية

إعداد ثابت جديد، itemsSnap، ليكون المجموعة الفرعية items. وبعد ذلك، كرِّر جميع المستندات في المجموعة.

// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
    .firestore.document("carts/{cartId}/items/{itemId}")
    .onWrite(async (change, context) => {
      console.log(`onWrite: ${change.after.ref.path}`);
      if (!change.after.exists) {
        // Ignore deletes
        return;
      }


      try {
        let totalPrice = 125.98;
        let itemCount = 8;

        const cartRef = db.collection("carts").doc(context.params.cartId);
        // ADD LINES FROM HERE
        const itemsSnap = await cartRef.collection("items").get();

        itemsSnap.docs.forEach(item => {
          const itemData = item.data();
        })
        // TO HERE
       
        return cartRef.update({
          totalPrice,
          itemCount
        });
      } catch(err) {
      }
    });

احتساب totalPrice وitemCount

لنبدأ أولًا في إعداد قيمتَي totalPrice وitemCount على صفر.

ثم أضف المنطق إلى كتلة التكرار. تأكَّد أولاً من أنّ العنصر يتضمّن سعرًا. إذا لم يتم تحديد كمية للسلعة، اضبط السمة كقيمة تلقائية على 1. بعد ذلك، أضِف الكمية إلى الإجمالي الحالي الذي يبلغ itemCount. أخيرًا، أضِف سعر السلعة مضروبًا في الكمية إلى الإجمالي المعروض حاليًا بقيمة totalPrice:

// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
    .firestore.document("carts/{cartId}/items/{itemId}")
    .onWrite(async (change, context) => {
      console.log(`onWrite: ${change.after.ref.path}`);
      if (!change.after.exists) {
        // Ignore deletes
        return;
      }

      try {
        // CHANGE THESE LINES
        let totalPrice = 0;
        let itemCount = 0;

        const cartRef = db.collection("carts").doc(context.params.cartId);
        const itemsSnap = await cartRef.collection("items").get();

        itemsSnap.docs.forEach(item => {
          const itemData = item.data();
          // ADD LINES FROM HERE
          if (itemData.price) {
            // If not specified, the quantity is 1
            const quantity = itemData.quantity ? itemData.quantity : 1;
            itemCount += quantity;
            totalPrice += (itemData.price * quantity);
          }
          // TO HERE
        })

        await cartRef.update({
          totalPrice,
          itemCount
        });
      } catch(err) {
      }
    });

يمكنك أيضًا إضافة تسجيل للمساعدة في تصحيح الأخطاء وحالات الخطأ:

// Recalculates the total cost of a cart; triggered when there's a change
// to any items in a cart.
exports.calculateCart = functions
    .firestore.document("carts/{cartId}/items/{itemId}")
    .onWrite(async (change, context) => {
      console.log(`onWrite: ${change.after.ref.path}`);
      if (!change.after.exists) {
        // Ignore deletes
        return;
      }

      let totalPrice = 0;
      let itemCount = 0;
      try {
        const cartRef = db.collection("carts").doc(context.params.cartId);
        const itemsSnap = await cartRef.collection("items").get();

        itemsSnap.docs.forEach(item => {
          const itemData = item.data();
          if (itemData.price) {
            // If not specified, the quantity is 1
            const quantity = (itemData.quantity) ? itemData.quantity : 1;
            itemCount += quantity;
            totalPrice += (itemData.price * quantity);
          }
        });

        await cartRef.update({
          totalPrice,
          itemCount
        });

        // OPTIONAL LOGGING HERE
        console.log("Cart total successfully recalculated: ", totalPrice);
      } catch(err) {
        // OPTIONAL LOGGING HERE
        console.warn("update error", err);
      }
    });

19- إعادة إجراء الاختبارات

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

$ npm test
> functions@ test .../emulators-codelab/codelab-initial-state/functions
> mocha

  shopping cart creation
    ✓ can be created by the cart owner (306ms)

  shopping cart reads, updates, and deletes
    ✓ cart can be read by the cart owner (59ms)

  shopping cart items
    ✓ items can be read by the cart owner
    ✓ items can be added by the cart owner

  adding an item to the cart recalculates the cart total. 
    ✓ should sum the cost of their items (800ms)


  5 passing (1s)

أحسنت!

20- جرِّبه باستخدام واجهة مستخدم "واجهة المحل".

للاختبار النهائي، ارجع إلى تطبيق الويب ( http://127.0.0.1:5000/) وأضف سلعة إلى سلة التسوق.

تأكَّد من تعديل سلة التسوّق باستخدام القيمة الإجمالية الصحيحة. رائع.

الملخّص

لقد تعرفت على حالة اختبار معقدة بين دوال Cloud Functions في Firebase وCloud Firestore. لقد كتبت دالة Cloud Function لإكمال الاختبار. لقد أكّدت أيضًا أنّ الوظيفة الجديدة تعمل في واجهة المستخدم. لقد فعلت كل هذا محليًا، مع تشغيل أدوات المحاكاة على جهازك الخاص.

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