Method: projects.test

測試 Source 的語法和語意正確性。系統偵測到的問題 (如果有的話) 會退回給呼叫端，並提供說明、嚴重程度和來源位置。

測試方法可使用 Source 執行。如要對新規則進行單元測試，傳遞 Source 會相當實用。

請注意，測試透過 REST API 執行時，會使用正式環境資料庫、儲存空間值區和相關 rsesource。這類測試可能會產生使用費用。強烈建議您使用 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

這個網址使用 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

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 或結果值與函式類型宣告不相容，系統就會將要求視為無效。

只要 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 將路徑區段視為經過編碼但使用未編碼分隔符 (「/」) 的網址。這是預設行為。
PLAIN 將總路徑視為非網址編碼，例如原始的 BERT 模型

運算式報表層級

運算式報表回應中包含的資料量。

列舉
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

來源片段的行號。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 測試失敗。

函式呼叫

代表在測試執行期間叫用的服務定義函式呼叫。

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

該運算式傳回的次數。