Firestore — בדיקות הרשאות באמולטור

בזמן בניית האפליקציה שלך, ייתכן שתרצה להגביל את הגישה למסד הנתונים Cloud Firestore שלך. עם זאת, לפני ההשקה, תזדקק ל-Cloud Firestore Security Rules מורכבים יותר. בעזרת האמולטור של Cloud Firestore, בנוסף ליצירת אב-טיפוס ובדיקת התכונות וההתנהגות הכללית של האפליקציה, ניתן לכתוב בדיקות יחידה (unit tests) הבודקות את ההתנהגות של ה-Cloud Firestore Security Rules שלך.

התחלה מהירה

עבור מספר מקרי בדיקה בסיסיים עם כללים פשוטים, נסה את מדגם ה-quickstart.

⁦Understand Cloud Firestore Security Rules⁩

הטמע Firebase Authentication ו-Cloud Firestore Security Rules עבור אימות, הרשאה ותיקוף נתונים ללא צורך בשרת (serverless), כאשר אתה משתמש בספריות הלקוח (client libraries) לנייד ולאינטרנט.

Cloud Firestore Security Rules כוללים שני חלקים:

• ביטוי match המזהה מסמכים במסד הנתונים שלך.

• ביטוי allow השולט בגישה למסמכים אלו.

Firebase Authentication מאמת את פרטי הזיהוי של המשתמשים ומספק את הבסיס למערכות גישה מבוססות משתמש ותפקידים.

כל בקשה למסד הנתונים מספרית לקוח (Rules mobile/web client library) מוערכת מול חוקי האבטחה שלך לפני קריאה או כתיבה של נתונים כלשהם. אם הכללים מונעים גישה לאחד מנתיבי המסמכים שצוינו, הבקשה כולה נכשלת.

למידע נוסף על Cloud Firestore Security Rules, עיין ב-Get started with Cloud Firestore Security Rules.

כדי להתקין את האמולטור ⁦Cloud Firestore⁩ השתמש ב-⁦Firebase⁩ ⁦CLI⁩ והפעל את הפקודה למטה:

⁦firebase setup:emulators:firestore⁩

הפעל את האמולטור

התחל באתחול פרויקט Firebase בספריית העבודה שלך. זהו צעד ראשון נפוץ בעת שימוש ב-Firebase CLI.

⁦firebase init⁩

הפעל את האמולטור באמצעות הפקודה הבאה. האמולטור ימשיך לרוץ עד שתסיים את התהליך (kill process):

⁦firebase emulators:start --only firestore⁩

במקרים רבים תרצה להפעיל את האמולטור, להריץ חבילת בדיקות ולאחר מכן לכבות את האמולטור לאחר סיום הבדיקות. ניתן לעשות זאת בקלות באמצעות הפקודה emulators:exec:

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

עם הפעלתו, האמולטור ינסה לפעול על יציאת (port) ברירת המחדל (8080). ניתן לשנות את יציאת האמולטור על ידי עריכת סעיף ה-"emulators" בקובץ ה-firebase.json שלך:

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

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

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

• האמולטור יטען בתחילה את הכללים שצוינו בשדה firestore.rules בקובץ ה-firebase.json שלך. הוא מצפה לשם של קובץ מקומי המכיל את ה-Cloud Firestore Security Rules ומחיל כללים אלו על כל הפרויקטים. אם לא תספק נתיב לקובץ מקומי או לא תשתמש בשיטת loadFirestoreRules כמתואר להלן, האמולטור יתייחס לכל הפרויקטים כבעלי כללים פתוחים.

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

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

הפעל בדיקות יחידה מקומית

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

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

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

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

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

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

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

אתה מייבא את הספרייה באמצעות ⁦v9⁩ הצהרות ייבוא ​​מודולריות. לְדוּגמָה:

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

לאחר הייבוא, יישום בדיקות יחידה כולל:

• יצירה והגדרה של RulesTestEnvironment באמצעות קריאה ל-initializeTestEnvironment.

• הגדרת נתוני בדיקה מבלי להפעיל את הכללים, תוך שימוש בשיטת נוחות המאפשרת לך לעקוף אותם באופן זמני: RulesTestEnvironment.withSecurityRulesDisabled.

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

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

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

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

⁦initializeTestEnvironment⁩() => ⁦RulesTestEnvironment⁩

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

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

השתמש באובייקט ההקשר של הבדיקה שהוחזר בבדיקות שלך כדי לגשת לכל מופעי האמולטור שהוגדרו, כולל אלה שהוגדרו עם ⁦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⁩()

הפעל פונקציית הגדרת בדיקה עם הקשר שמתנהג כאילו אבטחת ה-Rules מושבתת.

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

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

שיטה זו משמידה את כל ה-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'), { ... });⁩

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

ראה גם שיטות בדיקה נפוצות ופונקציות שירות ב-⁦v9⁩ ⁦SDK⁩ .

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

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

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

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

האמולטור של Cloud Firestore מאפשר לך להציג בקשות לקוח ב-Emulator Suite UI, כולל מעקב הערכה עבור Firebase Security Rules.

פתח את הכרטיסייה ⁦Firestore⁩ > ⁦Requests⁩ כדי להציג את רצף ההערכה המפורט עבור כל בקשה.

הפקת דוחות בדיקה

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

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

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

זה מפרק את הכללים שלך לביטויים ותת-ביטויים שניתן לרחף עליהם עם העכבר כדי לקבל מידע נוסף, כולל מספר ההערכות והערכים שהוחזרו. עבור הגרסה הגולמית (JSON) של נתונים אלה, כלול את ה-URL הבא בשאילתה שלך:

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

• אינך חייב ליצור פרויקט ⁦Cloud Firestore⁩ במפורש. האמולטור יוצר אוטומטית כל מופע שניגשת אליו.

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

כשאתה משתמש באמולטור Cloud Firestore, אתה עלול להיתקל בבעיות הידועות הבאות. עקוב אחר ההנחיות להלן כדי לפתור כל התנהגות חריגה שאתה חווה. הערות אלה נכתבו במחשבה על ספריית הבדיקות של ה-Security Rules, אך הגישות הכלליות חלות על כל Firebase SDK.

אם הבדיקות שלך עוברות ונכשלות לסירוגין, גם ללא שינויים בקוד הבדיקה עצמו, ייתכן שיהיה עליך לוודא שהן מסודרות כראוי. רוב האינטראקציות עם האמולטור הן אסינכרוניות, לכן ודא שכל הקוד האסינכרוני מסודר כהלכה. ניתן לתקן את הרצף על ידי שרשור promises או שימוש בכתיב await.

בפרט, סקור את פעולות האסינכרון הבאות:

• הגדרת חוקי אבטחה, לדוגמה באמצעות initializeTestEnvironment.