Method: projects.test

测试 Source 的语法和语义正确性。系统会将所存在的问题（如果有）返回给调用方，并附上说明、严重性和来源位置。

可以使用 Source 执行该测试方法。传递 Source 有助于对新规则进行单元测试。

请注意，使用 REST API 运行的测试使用生产数据库、存储分区和相关源代码。此类测试可能会产生使用费。我们强烈建议您使用 Firebase Local Emulator Suite 执行规则测试，因为您可以在离线非生产环境资源上运行测试，而不会产生使用费。

以下是 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

网址采用 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 实例的集合，用于验证规则的逻辑正确性。可以在 projects.test 调用内以内嵌方式引用 TestSuite，也可以将其作为 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)

请求上下文。

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

请求字段 类型
auth.uid string
auth.token 。 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 预计结果会被拒绝。

函数模拟

模拟规则函数定义。

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

只要 Arg 匹配器不同，就可以为给定的函数名称提供多个 FunctionMock。给定过载可能只有一个函数，其中所有 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 未指定编码。默认值为“网址_ENCODED”行为
URL_ENCODED 将路径段视为网址编码，但使用未编码的分隔符（“/”）。这是默认行为。
PLAIN 将总路径视为非网址编码，例如原始版本。

表达式报告级别

表达式报告响应中要包含的数据量。

枚举
LEVEL_UNSPECIFIED 未指定任何级别。默认值为“NONE”行为
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

源 fragment 的行号。从 1 开始。
column

integer

源代码行上与源 fragment 关联的第一列。
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 结构。请注意，与“visited 表达式”相反，此字段实际上是跟踪表达式，而不是权限语句字段。字面量表达式会被省略。

状态

测试结果的有效状态。

枚举
STATE_UNSPECIFIED 未设置测试状态。
SUCCESS 测试成功。
FAILURE 测试失败。

FunctionCall

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

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)

子表达式

值计数

一个元组，用于表示表达式的求值结果为特定 表达式 Value 的次数。

JSON 表示法 
{
  "value": value,
  "count": integer
}
字段
value

value (Value format)

表达式的返回值
count

integer

表达式返回的次数。