Method: projects.test

اختبار Source للتأكّد من الصحة النحوية والدلالية سيتم إرجاع المشاكل، إن وُجدت، إلى المتصل مع وصفها ودرجة الخطورة وموقع المصدر.

يمكن تنفيذ طريقة الاختبار باستخدام Source. يُعدّ اجتياز Source مفيدًا لاختبار القواعد الجديدة.

يُرجى العلم أنّ الاختبارات التي يتم إجراؤها باستخدام واجهة برمجة تطبيقات REST تستخدم قواعد بيانات الإنتاج وحِزم التخزين والمصادر والمصادر ذات الصلة. وقد يتم تحصيل رسوم استخدام من خلال هذا الاختبار. ننصحك بشدة باستخدام "حزمة أدوات المحاكاة المحلية من Firebase" لاختبار القواعد، لأنّه بإمكانك إجراء الاختبارات على موارد غير إنتاجية بلا اتصال بالإنترنت بدون رسوم استخدام.

في ما يلي مثال على السمة Source التي تسمح للمستخدمين بتحميل الصور إلى حزمة تحمل رقم تعريف المستخدم الخاص بهم وتتطابق مع البيانات الوصفية الصحيحة:

مثال

// Users are allowed to subscribe and unsubscribe to the blog.
service firebase.storage {
  match /users/{userId}/images/{imageName} {
      allow write: if userId == request.auth.uid
          && (imageName.matches('*.png$')
          || imageName.matches('*.jpg$'))
          && resource.mimeType.matches('^image/')
  }
}

طلب HTTP

POST https://firebaserules.googleapis.com/v1/{name=projects/**}:test

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

مَعلمات المسار

المَعلمات
name

string

مطلوب. لإجراء اختبارات مقابل source، يجب أن يشير اسم المورد إلى المشروع: التنسيق: projects/{project_id}

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "source": {
    object (Source)
  },
  "testSuite": {
    object (TestSuite)
  }
}
الحقول
source

object (Source)

سيتم التحقّق من صحة Source.
testSuite

object (TestSuite)

تمثّل هذه السمة TestSuite المضمّن المطلوب تنفيذه على Source.

عند توفير Source بشكل مضمّن، لن يتم تنفيذ حالات الاختبار إلا إذا كانت Source صالحة من الناحية التركيبية والدلالية.

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثّل هذه السمة الردّ على FirebaseRulesService.TestRuleset.

تمثيل JSON 
{
  "issues": [
    {
      object (Issue)
    }
  ],
  "testResults": [
    {
      object (TestResult)
    }
  ]
}
الحقول
issues[]

object (Issue)

مشاكل Source في النحو والدلالة متفاوتة الخطورة ستؤدي المشاكل ذات مستوى الخطورة ERROR إلى منع تنفيذ الاختبارات.
testResults[]

object (TestResult)

تمثّل هذه السمة مجموعة نتائج الاختبارات استنادًا إلى حالات الاختبار في TestSuite. ستظهر النتائج بالترتيب نفسه الذي تظهر به حالات الاختبار في TestSuite.

نطاقات الأذونات

يتطلب هذا الإعداد أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/firebase
  • https://www.googleapis.com/auth/firebase.readonly

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

مجموعة أدوات الاختبار

TestSuite هي مجموعة من مثيلات TestCase التي تتحقق من صحة القواعد المنطقية. قد تتم الإشارة إلى TestSuite بشكل مضمَّن في استدعاء projects.test أو كجزء من عنصر Release كفحص تجريبي.

تمثيل JSON 
{
  "testCases": [
    {
      object (TestCase)
    }
  ]
}
الحقول
testCases[]

object (TestCase)

جمع حالات الاختبار المرتبطة بـ TestSuite

حالة الاختبار

تقدّم رسائل TestCase سياق الطلب وتوقّع ما إذا كان سيتم السماح بالسياق المحدّد أو رفضه. قد تحدِّد حالات الاختبار request وresosurce وfunctionMocks من أجل محاكاة استدعاء دالة إلى دالة مقدَّمة من خلال خدمة.

يمثّل الكائن request السياق المتاح في وقت الطلب.

تشير السمة resource إلى قيمة المورد الهدف (مثل البيانات الوصفية لعنصر GCS أو مستند Firestore) كما تظهر في مساحة التخزين الدائمة قبل تنفيذ الطلب.

اطّلِع أيضًا على المستندات المرجعية ذات الصلة بخدمة Cloud Firestore ( الطلب والمورد) وCloud Storage for Firebase (طلب والمورد).

تمثيل JSON 
{
  "expectation": enum (Expectation),
  "request": value,
  "resource": value,
  "functionMocks": [
    {
      object (FunctionMock)
    }
  ],
  "pathEncoding": enum (PathEncoding),
  "expressionReportLevel": enum (ExpressionReportLevel)
}
الحقول
expectation

enum (Expectation)

اختبار التوقعات.
request

value (Value format)

اطلب سياقًا.

يعتمد التنسيق الدقيق لسياق الطلب على الخدمة. راجِع مستندات الخدمة المناسبة للحصول على معلومات عن الحقول والأنواع المتوافقة في الطلب. تتوافق جميع الخدمات على الأقل مع الحقول والأنواع التالية:

حقل الطلب النوع
معرِّف المصادقة string
رمز المصادقة map<string, string>
الرؤوس map<string, string>
method string
المَعلمات map<string, string>
المسار string
الوقت google.protobuf.Timestamp

إذا لم تكن قيمة الطلب مُنسّقة بشكل صحيح للخدمة، سيتم رفض الطلب كوسيطة غير صالحة.
resource

value (Value format)

قيمة اختيارية للمورد كما تظهر في مساحة التخزين الدائمة قبل تنفيذ الطلب.

يعتمد نوع المورد على قيمة request.path.
functionMocks[]

object (FunctionMock)

نماذج تجريبية لدالة "القواعد الاختيارية" للدوال المحدَّدة بالخدمة وفي حال ترك هذه السياسة بدون ضبط، من المتوقّع أن تعرض أي دالة "قواعد" محدّدة للخدمة خطأً، ما قد يؤثر أو لا يؤثّر في نتيجة الاختبار.
pathEncoding

enum (PathEncoding)

تحدِّد هذه السياسة ما إذا كان قد تم ترميز المسارات (مثل request.path) وطريقة إجراء ذلك.
expressionReportLevel

enum (ExpressionReportLevel)

لتحديد ما يجب تضمينه في الرد.

التوقّع

مجموعة التوقّعات المتوافقة مع حالة الاختبار.

تعدادات
EXPECTATION_UNSPECIFIED توقُّع غير محدَّد.
ALLOW قد تكون هناك نتيجة مسموح بها.
DENY من المتوقع أن تكون النتيجة مرفوضة.

نموذج FunctionMock

تعريف دالة "القواعد" الوهمية

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

يمكن تقديم أكثر من FunctionMock واحدة لاسم دالة معيّن ما دامت مطابقة Arg مختلفة. قد تكون هناك دالة واحدة فقط لحِمل زائد معيّن، حيث تكون جميع قيَم Arg هي Arg.any_value.

راجِع أيضًا الدوال بلغة "قواعد الأمان".

تمثيل JSON 
{
  "function": string,
  "args": [
    {
      object (Arg)
    }
  ],
  "result": {
    object (Result)
  }
}
الحقول
function

string

تمثّل هذه السمة اسم الدالة.

يجب أن يتطابق اسم الدالة مع الاسم الوارد في بيان الخدمة.
args[]

object (Arg)

قائمة قيم Arg المطلوب مطابقتها. الترتيب الذي يتم فيه تقديم الوسيطات هو الترتيب الذي يجب أن تظهر به في استدعاء الدالة.
result

object (Result)

النتيجة الوهمية لاستدعاء الدالة.

أرغ

مُطابقات الوسيطات للدالة الوهمية.

تمثيل JSON 
{

  // Union field type can be only one of the following:
  "exactValue": value,
  "anyValue": {
    object
  }
  // End of list of possible types for union field type.
}
الحقول
حقل الاتحاد type. قيم الوسيطات المسموح بها يمكن أن يكون type واحدًا فقط مما يلي:
exactValue

value (Value format)

الوسيطة تطابق تمامًا القيمة المقدمة.
anyValue

object

تطابق الوسيطة أي قيمة مقدمة.

النتيجة

قيم النتائج المحتملة من الاستدعاء التجريبي للدالة.

تمثيل JSON 
{

  // Union field type can be only one of the following:
  "value": value,
  "undefined": {
    object
  }
  // End of list of possible types for union field type.
}
الحقول
حقل الاتحاد type. قيم النتائج المسموح بها يمكن أن يكون type واحدًا فقط مما يلي:
value

value (Value format)

والنتيجة هي قيمة فعلية. يجب أن يتطابق نوع القيمة مع نوع النوع الذي تعلنه الخدمة.
undefined

object

النتيجة غير محددة، مما يعني أنه لا يمكن حساب النتيجة.

ترميز المسار

نوع ترميز المسار المستخدم.

تعدادات
ENCODING_UNSPECIFIED لم يتم تحديد أي ترميز. قيم افتراضية على "URL_ENCODED" السلوك.
URL_ENCODED يتم التعامل مع أجزاء المسار على أنّها عنوان URL مُرمَّز ولكن بفواصل غير مرمّزة ("/"). وهذا هو السلوك التلقائي.
PLAIN تتعامل مع المسار الإجمالي على أنّه ليس عنوان URL مرمّزًا، مثل: خام.

مستوى تقرير التعبير

مقدار البيانات المراد تضمينها في الرد على تقرير التعبير.

تعدادات
LEVEL_UNSPECIFIED لم يتم تحديد أي مستوى. القيم التلقائية على "بدون" السلوك.
NONE لا تُدرِج أيّ معلومات إضافية.
FULL تضمين تقارير تفصيلية عن التعبيرات التي تم تقييمها
VISITED قم فقط بتضمين التعبيرات التي تمت زيارتها أثناء التقييم.

مشكلة

تشمل المشاكل التحذيرات والأخطاء وإشعارات الإيقاف.

تمثيل JSON 
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "description": string,
  "severity": enum (Severity)
}
الحقول
sourcePosition

object (SourcePosition)

موضع المشكلة في Source
description

string

وصف مختصر للخطأ.
severity

enum (Severity)

درجة خطورة المشكلة.

موضع المصدر

الموضع في محتوى Source، بما في ذلك السطر ورقم العمود وفهرس File في رسالة Source يُستخدَم لأغراض تصحيح الأخطاء.

تمثيل JSON 
{
  "fileName": string,
  "line": integer,
  "column": integer,
  "currentOffset": integer,
  "endOffset": integer
}
الحقول
fileName

string

اسم جهاز File
line

integer

رقم السطر للجزء المصدر. يستند إلى 1.
column

integer

العمود الأول في سطر المصدر المرتبط بجزء المصدر
currentOffset

integer

موضع البدء بالنسبة إلى بداية الملف.
endOffset

integer

موضع النهاية بالنسبة إلى بداية الملف.

درجة الخطورة

تمثّل هذه السمة مجموعة شدة المشكلة.

تعدادات
SEVERITY_UNSPECIFIED درجة خطورة غير محدّدة
DEPRECATION مشكلة إيقاف البيانات والطريقة التي ربما لم تعد متاحة أو لم تعد متاحة
WARNING تحذيرات مثل: المتغيّرات غير المستخدَمة.
ERROR أخطاء مثل: الأقواس المعقوفة غير المتطابقة أو إعادة التعريف المتغيّرة.

TestResult

رسالة نتيجة الاختبار تحتوي على حالة الاختبار بالإضافة إلى وصف وموضع المصدر لحالات تعذُّر الاختبار.

تمثيل JSON 
{
  "state": enum (State),
  "debugMessages": [
    string
  ],
  "errorPosition": {
    object (SourcePosition)
  },
  "functionCalls": [
    {
      object (FunctionCall)
    }
  ],
  "visitedExpressions": [
    {
      object (VisitedExpression)
    }
  ],
  "expressionReports": [
    {
      object (ExpressionReport)
    }
  ]
}
الحقول
state

enum (State)

حالة الاختبار.
debugMessages[]

string

تصحيح أخطاء الرسائل ذات الصلة بمشاكل تنفيذ الاختبار التي حدثت أثناء التقييم.

قد تكون رسائل تصحيح الأخطاء مرتبطة بعدد كبير جدًا أو قليل جدًا من الاستدعاءات لنماذج الدوال أو أخطاء وقت التشغيل التي تحدث أثناء التقييم.

مثلاً: Unable to read variable [name: "resource"]
errorPosition

object (SourcePosition)

تمثّل هذه السمة موضع حدوث الخطأ في بيئة التشغيل الأساسية في Source.

قد يؤدي تقييم تعبير إلى حدوث خطأ. يتم رفض القواعد تلقائيًا، وبالتالي يكون توقُّع DENY عند حدوث خطأ صالحًا. عندما تكون هناك رسالة DENY مع وجود خطأ، يتم عرض SourcePosition.

مثلاً: errorPosition { line: 19 column: 37 }
functionCalls[]

object (FunctionCall)

مجموعة استدعاءات الدوال التي يتم إجراؤها للطرق المحددة للخدمة.

يتم تضمين طلبات الدوال بالترتيب الذي تظهر به خلال عملية التقييم، ويتم توفيرها لكل من الدالتَين النموذجيتَين وغير النموذجيتَين، ويتم تضمين هذه الطلبات في الاستجابة بغض النظر عن اختبار state.
visitedExpressions[]

object (VisitedExpression)

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

match /path {
  allow read if: <expr>
}

للحصول على تقرير تفصيلي عن حالات التقييم الوسيطة، يُرجى الاطّلاع على حقل expressionReports.
expressionReports[]

object (ExpressionReport)

التعيين من التعبير في AST لمجموعة القواعد إلى القيم التي تم تقييمها لها. مدمجة جزئيًا لتعكس بنية AST. يُرجى ملاحظة أن هذا الحقل يتتبع في الواقع التعبيرات وليس عبارات الأذونات على عكس "visitedExpressions". أعلاه. يتم حذف التعبيرات الحرفية.

الولاية

الحالات الصالحة لنتيجة الاختبار

تعدادات
STATE_UNSPECIFIED لم يتم ضبط حالة الاختبار.
SUCCESS نجح الاختبار.
FAILURE تعذّر الاختبار.

دالة FunctionCall

يمثل هذا الإعداد استدعاء دالة محددة للخدمة تم استدعاؤها أثناء التنفيذ التجريبي.

تمثيل JSON 
{
  "function": string,
  "args": [
    value
  ]
}
الحقول
function

string

تم استدعاء اسم الدالة.
args[]

value (Value format)

الوسيطات التي تم توفيرها للدالة.

تمت زيارة Expression

تخزين الموضع ونتائج الوصول لتعبير تمت زيارته في القواعد

تمثيل JSON 
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "value": value
}
الحقول
sourcePosition

object (SourcePosition)

الموضع في Source حيث تم الانتقال إلى تعبير.
value

value (Value format)

القيمة المُقيّمة للتعبير الذي تمت زيارته، مثل صواب/خطأ

تقرير التعبيرات

تصف مكان العثور على تعبير في ملف وما تم تقييمه على مدار استخدامه.

تمثيل JSON 
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "values": [
    {
      object (ValueCount)
    }
  ],
  "children": [
    {
      object (ExpressionReport)
    }
  ]
}
الحقول
sourcePosition

object (SourcePosition)

موضع التعبير في مصدر القواعد الأصلية
values[]

object (ValueCount)

القيم التي تم تقييم هذا التعبير عليها عند العثور عليها.
children[]

object (ExpressionReport)

تعبيرات فرعية

عدد القيم

صف لعدد المرات التي تم فيها تقييم تعبير لقيمة تعبير معينة.

تمثيل JSON 
{
  "value": value,
  "count": integer
}
الحقول
value

value (Value format)

القيمة المعروضة للتعبير
count

integer

عدد مرات عرض هذا التعبير.