Method: projects.test

Тестовый Source на синтаксическую и семантическую корректность. Присутствующие проблемы, если таковые имеются, будут возвращены вызывающему абоненту с описанием, серьезностью и местоположением источника.

Тестовый метод может быть выполнен с помощью Source . Передача Source полезна для модульного тестирования новых правил.

Обратите внимание, что тесты, выполняемые с использованием REST API, используют рабочие базы данных, сегменты хранения и связанные ресурсы. За такое тестирование может взиматься плата за использование. Мы настоятельно рекомендуем вам использовать пакет локального эмулятора 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 ( request , resources ) и Cloud Storage for Firebase ( request , resources ).

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 )

Дополнительная функция Rules имитирует определяемые службой функции. Если этот параметр не установлен, ожидается, что любая определяемая службой функция правил будет возвращать ошибку, которая может повлиять или не повлиять на результат теста.

pathEncoding

enum ( PathEncoding )

Указывает, кодируются ли пути (например, request.path) и каким образом.

expressionReportLevel

enum ( ExpressionReportLevel )

Указывает, что должно быть включено в ответ.

Ожидание

Набор поддерживаемых ожиданий тестовых примеров.

Перечисления
EXPECTATION_UNSPECIFIED Неопределенное ожидание.
ALLOW Ожидайте разрешенного результата.
DENY Ожидайте отрицательный результат.

ФункцияMock

Определение функции Mock Rules.

Mocks должны ссылаться на функцию, объявленную целевой службой. Тип функции args и результат будут определены во время тестирования. Если значения аргумента или результата несовместимы с объявлением типа функции, запрос будет считаться недействительным.

Для данного имени функции может быть предоставлено более одного 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 Такие ошибки, как: несовпадающие фигурные скобки или переопределение переменной.

Результат теста

Сообщение о результате теста, содержащее состояние теста, а также описание и источник ошибок теста.

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 )

Подвыражения

ValueCount

Кортеж, показывающий, сколько раз выражение оценивалось по определенному значению ExpressionValue.

JSON-представление 
{
  "value": value,
  "count": integer
}
Поля
value

value ( Value format)

Возвращаемое значение выражения

count

integer

Сколько раз возвращалось это выражение.