Firebase — בדיקות Security Rules

ה-Firebase Local Emulator Suite מקל על אימות מלא של התכונות וההתנהגות של האפליקציה שלך. זהו גם כלי נהדר לאימות הגדרות ה-Firebase Security Rules שלך. השתמש ב-Firebase Emulators כדי להריץ ולהפוך בדיקות יחידה (unit tests) לאוטומטיות בסביבה מקומית. השיטות המתוארות במסמך זה אמורות לסייע לך בבנייה ובאוטומציה של בדיקות יחידה עבור האפליקציה שלך, המאמתות את ה-Security Rules שלך.

אם עדיין לא עשית זאת, הגדר את ⁦Firebase Emulators⁩ .

לפני שתפעיל את האמולטור

לפני שתתחיל להשתמש באמולטור, זכור את הדברים הבאים:

• האמולטור יטען בתחילה את הכללים שצוינו בשדה firestore.rules או storage.rules של הקובץ ⁦firebase.json⁩ שלך. אם הקובץ לא קיים ואינך משתמש בשיטת ⁦loadFirestoreRules⁩ או ⁦loadStorageRules⁩ כפי שמתואר להלן, האמולטור מתייחס לכל הפרויקטים כבעלי כללים פתוחים.

• בעוד שרוב ה-Firebase SDKs עובדים ישירות עם האמולטורים, רק ספריית @firebase/rules-unit-testing תומכת ב-mocking של הרשאות (auth) ב-Security Rules, מה שהופך את בדיקות היחידה לפשוטות הרבה יותר. בנוסף, הספרייה תומכת בכמה תכונות ספציפיות לאמולטור כמו ניקוי כל הנתונים, כמפורט להלן.

• האמולטורים מקבלים גם אסימוני (tokens) Firebase Auth של סביבת הייצור המסופקים דרך Client SDKs ומעריכים את הכללים בהתאם, מה שמאפשר לחבר את האפליקציה שלך ישירות לאמולטורים לצורך בדיקות אינטגרציה ובדיקות ידניות.

הבדלים בין אמולטורים של מסד הנתונים לייצור

• אינך חייב ליצור במפורש מופע מסד נתונים. האמולטור יצור אוטומטית כל מופע מסד נתונים שאליו ניגשים.

• כל מסד נתונים חדש מתחיל עם כללים סגורים, כך שמשתמשים שאינם מנהלי מערכת לא יוכלו לקרוא או לכתוב.

• כל מסד נתונים מחקה מחיל את מגבלות התוכנית והמכסות ⁦Spark⁩ (בעיקר, זה מגביל כל מופע ל-100 חיבורים במקביל).

• כל מסד נתונים יקבל את המחרוזת "בעלים" כאסימון אישור מנהל.

• לאמולטורים אין כרגע אינטראקציות פעילות עם מוצרי Firebase אחרים. חשוב לציין שהזרימה הרגילה של Firebase Authentication אינה עובדת. במקום זאת, ניתן להשתמש בשיטת initializeTestApp() בספריית ה-rules-unit-testing, המקבלת שדה auth. אובייקט ה-Firebase שנוצר בשיטה זו מתנהג כאילו הוא עבר אימות מוצלח כישות שתספק. אם תעביר null, הוא יתנהג כמשתמש לא מאומת (למשל, כללי auth != null ייכשלו).

אינטראקציה עם האמולטור ⁦Realtime Database⁩

מופע Firebase Realtime Database בסביבת ייצור נגיש בתת-דומיין של firebaseio.com, וניתן לגשת ל-REST API באופן הבא:

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 ⁦JavaScript⁩ ⁦SDK⁩

Firebase מפיצה ספריית בדיקות יחידה ל-Security Rules עם גרסה 9 של ה-JavaScript SDK ועם גרסה 8. ה-APIs של הספריות שונים משמעותית. אנו ממליצים על ספריית הבדיקות v9, שהיא יעילה יותר ודורשת פחות הגדרות כדי להתחבר לאמולטורים, ובכך נמנעת בבטחה משימוש מקרי במשאבי סביבת ייצור. עבור תאימות לאחור, אנו ממשיכים לספק את ספריית הבדיקות v8.

• שיטות בדיקה ופונקציות שירות נפוצות ב-⁦v9⁩ ⁦SDK⁩

• שיטות בדיקה ספציפיות לאמולטור ב-⁦v9⁩ ⁦SDK⁩

השתמש במודול @firebase/rules-unit-testing כדי ליצור אינטראקציה עם האמולטור שפועל באופן מקומי. אם אתה מקבל פסקי זמן או שגיאות ⁦ECONNREFUSED⁩, בדוק שוב שהאמולטור אכן פועל.

אנו ממליצים בחום להשתמש בגרסה עדכנית של Node.js כדי שתוכל להשתמש בכתיב async/await. כמעט כל התנהגות שתרצה לבדוק כוללת פונקציות אסינכרוניות, ומודול הבדיקה תוכנן לעבוד עם קוד מבוסס Promise.

הספרייה ⁦v9⁩ ⁦Rules Unit Testing⁩ תמיד מודעת לאמולטורים ולעולם לא נוגעת במשאבי הייצור שלך.

אתה מייבא את הספרייה באמצעות הצהרות ייבוא מודולריות של v9. לדוגמה:

⁦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.

• הגדרת נתוני בדיקה מבלי להפעיל Security Rules, באמצעות שיטת עזר המאפשרת לעקוף אותם זמנית, RulesTestEnvironment.withSecurityRulesDisabled.

• הגדרת חבילת בדיקות (test suite) ו-hooks מסוג before/after עבור כל בדיקה, עם קריאות לניקוי נתוני בדיקה וסביבה, כגון RulesTestEnvironment.cleanup() או RulesTestEnvironment.clearFirestore().

• יישום מקרי בדיקה המחקים מצבי אימות באמצעות ⁦RulesTestEnvironment⁩.⁦authenticatedContext⁩ ו-⁦RulesTestEnvironment⁩.⁦unauthenticatedContext⁩ .

שיטות נפוצות ופונקציות שירות

ראה גם שיטות בדיקה ספציפיות לאמולטור באמצעות ⁦API⁩ המודולרי.

⁦initializeTestEnvironment⁩() => ⁦RulesTestEnvironment⁩

פונקציה זו מאתחלת סביבת בדיקה עבור בדיקות יחידה של חוקים (rules unit testing). קרא לפונקציה זו ראשונה כדי להגדיר את הבדיקה. ביצוע מוצלח מחייב שהאמולטורים ירוצו.

הפונקציה מקבלת אובייקט אופציונלי המגדיר TestEnvironmentConfig, שיכול לכלול מזהה פרויקט (project ID) והגדרות תצורה של האמולטור.

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

⁦RulesTestEnvironment⁩.⁦authenticatedContext⁩({ ⁦user_id⁩: מחרוזת, ⁦tokenOptions⁩?: TokenOptions }) => ⁦RulesTestContext⁩

שיטה זו יוצרת RulesTestContext, שמתנהג כמו משתמש Authentication מאומת. לבקשות שיווצרו דרך ההקשר המוחזר יצורף אסימון Authentication מדומה. לחלופין, ניתן להעביר אובייקט המגדיר custom claims או עקיפות עבור ה-payloads של אסימוני ה-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 () . doc ( '/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 מושבתים.

שיטה זו מקבלת פונקציית callback, שמקבלת את ההקשר שעוקף את ה-Security Rules ומחזירה Promise. ההקשר יושמד ברגע שה-Promise יסתיים (resolve/reject).

שיטה זו הורסת את כל ⁦RulesTestContexts⁩ שנוצרו בסביבת הבדיקה ומנקה את המשאבים הבסיסיים, ומאפשרת יציאה נקייה.

שיטה זו אינה משנה את מצב האמולטורים בשום צורה. כדי לאפס נתונים בין בדיקות, השתמש בשיטת ניקוי הנתונים הספציפית לאמולטור האפליקציה.

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

הפונקציה מוודאת שה-Promise המסופק, העוטף פעולת אמולטור, יסתיים ללא הפרות של Security Rules.

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

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

הפונקציה מוודאת שה-Promise המסופק, העוטף פעולת אמולטור, יידחה עקב הפרת Security Rules.

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

שיטות ספציפיות לאמולטור

ראה גם שיטות בדיקה נפוצות ופונקציות שירות באמצעות ⁦API⁩ המודולרי.

⁦Cloud Firestore⁩

⁦RulesTestEnvironment⁩.⁦clearFirestore⁩() => ⁦Promise⁩<void>

שיטה זו מנקה נתונים במסד הנתונים ⁦Firestore⁩ השייכים ל-⁦projectId⁩ המוגדר עבור האמולטור ⁦Firestore⁩.

⁦RulesTestContext.firestore⁩(הגדרות?: ⁦Firestore.FirestoreSettings⁩) => ⁦Firestore⁩;

שיטה זו מקבלת מופע Firestore עבור הקשר בדיקה זה. ניתן להשתמש במופע ה-Firebase JS Client SDK שמוחזר עם ה-APIs של ה-client SDK (מודולרי v9 או v9 compat).

⁦Realtime Database⁩

⁦RulesTestEnvironment⁩.⁦clearDatabase⁩() => ⁦Promise⁩<void>

שיטה זו מנקה נתונים ב-⁦Realtime Database⁩ השייכים ל-⁦projectId⁩ המוגדר עבור האמולטור ⁦Realtime Database⁩.

⁦RulesTestContext.database⁩(⁦databaseURL⁩?: ⁦Firestore.FirestoreSettings⁩) => ⁦Firestore⁩;

קבל מופע Realtime Database עבור הקשר בדיקה זה. ניתן להשתמש במופע ה-Firebase JS Client SDK שמוחזר עם ה-APIs של ה-client SDK (מודולרי או מבוסס שמות, גרסה 9 ומעלה). השיטה מקבלת URL של מופע ה-Realtime Database. אם צוין, יוחזר מופע עבור גרסה מדומה של ה-namespace עם פרמטרים שחולצו מה-URL.

⁦Cloud Storage⁩

⁦RulesTestEnvironment⁩.⁦clearStorage⁩() => ⁦Promise⁩<void>

שיטה זו מנקה אובייקטים ומטא נתונים בדלי אחסון השייכים ל-⁦projectId⁩ המוגדר עבור האמולטור ⁦Cloud Storage⁩.

⁦RulesTestContext.storage⁩(⁦bucketUrl⁩?: string) => ⁦Firebase Storage⁩;

שיטה זו מחזירה מופע ⁦Storage⁩ שהוגדר להתחבר לאמולטור. השיטה מקבלת כתובת URL gs:// ל-⁦Firebase⁩ ⁦Storage Bucket⁩ לבדיקה. אם צוין, מחזיר מופע ⁦Storage⁩ עבור גרסה מדומה של שם הדלי.

הפעל בדיקות יחידה מקומית עם ⁦v8⁩ JavaScript ⁦SDK⁩

בחר מוצר כדי לראות את השיטות המשמשות את ⁦Firebase Test⁩ ⁦SDK⁩ להתממשק עם האמולטור.

⁦initializeTestApp⁩({ ⁦projectId⁩: מחרוזת, אישור: אובייקט }) => ⁦FirebaseApp⁩

שיטה זו מחזירה אפליקציית Firebase מאותחלת התואמת למזהה הפרויקט (project ID) ומשתנה האימות (auth) שצוינו באפשרויות. השתמש בזה כדי ליצור אפליקציה מאומתת כמשתמש ספציפי לשימוש בבדיקות.

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

⁦initializeAdminApp⁩({ ⁦projectId⁩: מחרוזת }) => ⁦FirebaseApp⁩

שיטה זו מחזירה אפליקציית Firebase מורשית (admin) מאותחלת. אפליקציה זו עוקפת את חוקי האבטחה בעת ביצוע קריאות וכתיבות. השתמש בזה כדי ליצור אפליקציה מאומתת כמנהל לצורך הגדרת מצב לבדיקות.

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

apps() => [FirebaseApp] שיטה זו מחזירה את כל אפליקציות הבדיקה והניהול המאותחלות כעת. השתמש בזה כדי לנקות אפליקציות בין בדיקות או אחריהן.

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

⁦loadFirestoreRules⁩({ ⁦projectId⁩: מחרוזת, כללים: אובייקט }) => ⁦Promise⁩

שיטה זו שולחת חוקים למסד נתונים הפועל באופן מקומי. היא מקבלת אובייקט המציין את החוקים כמחרוזת. השתמש בשיטה זו כדי להגדיר את חוקי מסד הנתונים שלך.

בסיס אש . ⁦loadFirestoreRules⁩ ({ ⁦projectId⁩ : "my-test-project" , חוקים : fs . ⁦readFileSync⁩ ( "/path/to/firestore.rules" , "⁦utf8⁩") });

שיטה זו מחזירה Promise שנדחה אם הקלט מצליח, או מצליח אם הקלט נדחה. השתמש בזה כדי לקבוע אם קריאה או כתיבה למסד נתונים נכשלות.

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