测试Source
的语法和语义正确性。存在的问题(如果有)将返回给调用者,并附上描述、严重性和来源位置。
测试方法可以使用Source
执行。传递Source
对于新规则的单元测试很有用。
请注意,使用 REST API 运行的测试使用生产数据库、存储桶和相关资源。此类测试可能会产生使用费。我们强烈建议您使用 Firebase 本地模拟器套件执行规则测试,因为您可以在离线、非生产资源上运行测试,而无需支付使用费。
以下是Source
的示例,允许用户将图像上传到带有其用户 ID 并匹配正确元数据的存储桶:
例子
// 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 | 必需的。对于针对 |
请求正文
请求正文包含具有以下结构的数据:
JSON 表示 | |
---|---|
{ "source": { object ( |
领域 | |
---|---|
source | 需要检查 |
testSuite | 针对 当内联提供 |
响应体
如果成功,响应正文包含具有以下结构的数据:
JSON 表示 | |
---|---|
{ "issues": [ { object ( |
领域 | |
---|---|
issues[] | 不同严重程度的句法和语义 |
testResults[] | |
授权范围
需要以下 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 ( |
领域 | |
---|---|
testCases[] | 与 |
测试用例
TestCase
消息提供请求上下文以及对给定上下文是否被允许或拒绝的期望。测试用例可以指定request
、 resosurce
和functionMocks
来模拟对服务提供的函数的函数调用。
request
对象表示请求时存在的上下文。
resource
是执行请求之前出现在持久存储中的目标资源的值(例如,GCS 对象或 Firestore 文档的元数据)。
另请参阅 Cloud Firestore(请求、资源)和 Cloud Storage for Firebase(请求、资源)的相关参考文档。
JSON 表示 | |
---|---|
{ "expectation": enum ( |
领域 | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
expectation | 测试期望。 | ||||||||||||||||
request | 请求上下文。 请求上下文的确切格式取决于服务。有关请求支持的字段和类型的信息,请参阅相应的服务文档。至少,所有服务都支持以下字段和类型:
如果请求值对于服务而言格式不正确,则该请求将作为无效参数而被拒绝。 | ||||||||||||||||
resource | 在满足请求之前出现在持久存储中的可选资源值。 资源类型取决于 | ||||||||||||||||
functionMocks[] | 服务定义函数的可选规则函数模拟。如果未设置,则任何服务定义的规则函数都将返回错误,这可能会也可能不会影响测试结果。 | ||||||||||||||||
pathEncoding | 指定是否对路径(例如 request.path)进行编码以及如何编码。 | ||||||||||||||||
expressionReportLevel | 指定响应中应包含的内容。 |
期待
支持的测试用例期望集。
枚举 | |
---|---|
EXPECTATION_UNSPECIFIED | 未指定的期望。 |
ALLOW | 期待一个允许的结果。 |
DENY | 期待被拒绝的结果。 |
函数模拟
模拟规则函数定义。
模拟必须引用目标服务声明的函数。函数 args 和结果的类型将在测试时推断。如果 arg 或结果值与函数类型声明不兼容,则请求将被视为无效。
只要Arg
匹配器不同,就可以为给定的函数名称提供多个FunctionMock
。对于给定的重载,可能只有一个函数,其中所有Arg
值都是Arg.any_value
。
另请参见安全规则语言中的函数。
JSON 表示 | |
---|---|
{ "function": string, "args": [ { object ( |
领域 | |
---|---|
function | 函数的名称。 函数名称必须与服务声明提供的名称匹配。 |
args[] | 要匹配的 |
result | 函数调用的模拟结果。 |
精氨酸
模拟函数的 Arg 匹配器。
JSON 表示 | |
---|---|
{ // Union field |
领域 | ||
---|---|---|
联合字段type 。支持的参数值。 type 只能是以下之一: | ||
exactValue | 参数与提供的值完全匹配。 | |
anyValue | 参数与提供的任何值匹配。 |
结果
函数模拟调用的可能结果值。
JSON 表示 | |
---|---|
{ // Union field |
领域 | ||
---|---|---|
联合字段type 。支持的结果值。 type 只能是以下之一: | ||
value | 结果是实际值。值的类型必须与服务声明的类型匹配。 | |
undefined | 结果未定义,意味着无法计算结果。 |
路径编码
使用的路径编码类型。
枚举 | |
---|---|
ENCODING_UNSPECIFIED | 未指定编码。默认为“URL_ENCODED”行为。 |
URL_ENCODED | 将路径段视为 URL 编码但带有非编码分隔符(“/”)。这是默认行为。 |
PLAIN | 将总路径视为非 URL 编码,例如原始路径。 |
表达报告级别
表达式报告响应中包含的数据量。
枚举 | |
---|---|
LEVEL_UNSPECIFIED | 没有指定级别。默认为“无”行为。 |
NONE | 不要包含任何附加信息。 |
FULL | 包括有关评估表达式的详细报告。 |
VISITED | 仅包括评估期间访问的表达式。 |
问题
问题包括警告、错误和弃用通知。
JSON 表示 | |
---|---|
{ "sourcePosition": { object ( |
领域 | |
---|---|
sourcePosition | 问题在 |
description | 简短的错误描述。 |
severity | 问题的严重性。 |
源位置
Source
内容中的位置,包括Source
消息中File
的行号、列号和索引。用于调试目的。
JSON 表示 | |
---|---|
{ "fileName": string, "line": integer, "column": integer, "currentOffset": integer, "endOffset": integer } |
领域 | |
---|---|
fileName | |
line | 源片段的行号。 1 为基础。 |
column | 与源片段关联的源行上的第一列。 |
currentOffset | 相对于文件开头的起始位置。 |
endOffset | 相对于文件开头的结束位置。 |
严重性
问题严重性的集合。
枚举 | |
---|---|
SEVERITY_UNSPECIFIED | 未指定的严重程度。 |
DEPRECATION | 可能不再支持或维护的语句和方法的弃用问题。 |
WARNING | 警告例如:未使用的变量。 |
ERROR | 错误例如:不匹配的花括号或变量重新定义。 |
测试结果
测试结果消息包含测试状态以及测试失败的描述和源位置。
JSON 表示 | |
---|---|
{ "state": enum ( |
领域 | |
---|---|
state | 测试状态。 |
debugMessages[] | 与评估期间遇到的测试执行问题相关的调试消息。 调试消息可能与过多或过少的函数模拟调用或评估期间发生的运行时错误有关。 例如: |
errorPosition | 表达式的求值可能会导致错误。默认情况下规则是拒绝的,因此生成错误时的 例如 |
functionCalls[] | 对服务定义的方法进行的函数调用集。 函数调用按照在评估期间遇到的顺序包含在内,为模拟和未模拟的函数提供,并且无论测试 |
visitedExpressions[] | 给定测试的访问权限表达式集。这将返回与测试用例相关的所有访问权限表达式的位置和评估结果,例如
有关中间评估状态的详细报告,请参阅 |
expressionReports[] | 从规则集 AST 中的表达式到它们求值的值的映射。部分嵌套以镜像 AST 结构。请注意,与上面的“visitedExpressions”字段相比,该字段实际上是跟踪表达式而不是权限语句。省略了文字表达。 |
状态
测试结果的有效状态。
枚举 | |
---|---|
STATE_UNSPECIFIED | 未设置测试状态。 |
SUCCESS | 测试成功。 |
FAILURE | 测试失败。 |
函数调用
表示在测试执行期间调用的服务定义的函数调用。
JSON 表示 | |
---|---|
{ "function": string, "args": [ value ] } |
领域 | |
---|---|
function | 调用的函数的名称。 |
args[] | 提供给函数的参数。 |
访问表达式
存储规则中访问的表达式的位置和访问结果。
JSON 表示 | |
---|---|
{
"sourcePosition": {
object ( |
领域 | |
---|---|
sourcePosition | |
value | 访问表达式的评估值,例如 true/false |
表达报告
描述在文件中的何处找到表达式以及在使用过程中对其求值的结果。
JSON 表示 | |
---|---|
{ "sourcePosition": { object ( |
领域 | |
---|---|
sourcePosition | 表达式在原始规则源中的位置。 |
values[] | 该表达式在遇到时求值的值。 |
children[] | 子表达式 |
值计数
表达式被计算为特定 ExpressionValue 的次数的元组。
JSON 表示 | |
---|---|
{ "value": value, "count": integer } |
领域 | |
---|---|
value | 表达式的返回值 |
count | 该表达式返回的次数。 |