Method: projects.test

测试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

string

必需的。对于针对source测试，资源名称必须引用项目：格式： projects/{project_id}

请求正文

请求正文包含具有以下结构的数据：

JSON 表示
{
  "source": {
    object (Source)
  },
  "testSuite": {
    object (TestSuite)
  }
}
领域
source

object ( Source )

需要检查Source的正确性。

testSuite

object ( TestSuite )

针对Source执行的内联TestSuite 。

当内联提供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)

请求上下文。

请求上下文的确切格式取决于服务。有关请求支持的字段和类型的信息，请参阅相应的服务文档。至少，所有服务都支持以下字段和类型：

请求字段类型
授权uid string
授权令牌map<string, string>
标头map<string, string>
方法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期待被拒绝的结果。

函数模拟

模拟规则函数定义。

模拟必须引用目标服务声明的函数。函数 args 和结果的类型将在测试时推断。如果 arg 或结果值与函数类型声明不兼容，则请求将被视为无效。

只要Arg匹配器不同，就可以为给定的函数名称提供多个FunctionMock 。对于给定的重载，可能只有一个函数，其中所有Arg值都是Arg.any_value 。

另请参见安全规则语言中的函数。

JSON 表示
{
  "function": string,
  "args": [
    {
      object (Arg)
    }
  ],
  "result": {
    object (Result)
  }
}
领域
function

string

函数的名称。

函数名称必须与服务声明提供的名称匹配。

args[]

object ( Arg )

要匹配的Arg值列表。提供参数的顺序就是它们在函数调用中必须出现的顺序。

result

object ( Result )

函数调用的模拟结果。

精氨酸

模拟函数的 Arg 匹配器。

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内容中的位置，包括Source消息中File的行号、列号和索引。用于调试目的。

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错误例如：不匹配的花括号或变量重新定义。

测试结果

测试结果消息包含测试状态以及测试失败的描述和源位置。

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测试失败。

函数调用

表示在测试执行期间调用的服务定义的函数调用。

JSON 表示
{
  "function": string,
  "args": [
    value
  ]
}
领域
function

string

调用的函数的名称。

args[]

value ( Value format)

提供给函数的参数。

访问表达式

存储规则中访问的表达式的位置和访问结果。

JSON 表示
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "value": value
}
领域
sourcePosition

object ( SourcePosition )

Source中访问表达式的位置。

value

value ( Value format)

访问表达式的评估值，例如 true/false

表达报告

描述在文件中的何处找到表达式以及在使用过程中对其求值的结果。

JSON 表示
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "values": [
    {
      object (ValueCount)
    }
  ],
  "children": [
    {
      object (ExpressionReport)
    }
  ]
}
领域
sourcePosition

object ( SourcePosition )

表达式在原始规则源中的位置。

values[]

object ( ValueCount )

该表达式在遇到时求值的值。

children[]

object ( ExpressionReport )

子表达式

值计数

表达式被计算为特定 ExpressionValue 的次数的元组。

JSON 表示
{
  "value": value,
  "count": integer
}
领域
value

value ( Value format)

表达式的返回值

count

integer

该表达式返回的次数。