Method: projects.test

Source de teste para correção sintática e semântica. Os problemas presentes, se houver, serão retornados ao chamador com descrição, gravidade e localização de origem.

O método de teste pode ser executado com Source . Passar Source é útil para testes unitários de novas regras.

Observe que os testes executados usando a API REST usam bancos de dados de produção, buckets de armazenamento e recursos relacionados. Esses testes podem incorrer em cobranças de uso. Recomendamos fortemente que você use o Firebase Local Emulator Suite para realizar testes de regras, já que é possível executar testes off-line em recursos que não sejam de produção, sem cobranças de uso.

A seguir está um exemplo de Source que permite aos usuários fazer upload de imagens para um intervalo que contém seu ID de usuário e corresponde aos metadados corretos:

Exemplo

// 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/')
  }
}

Solicitação HTTP

POST https://firebaserules.googleapis.com/v1/{name=projects/**}:test

A URL usa sintaxe de transcodificação gRPC .

Parâmetros de caminho

Parâmetros
name

string

Obrigatório. Para testes em source , o nome do recurso deve fazer referência ao projeto: Formato: projects/{project_id}

Solicitar corpo

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON
{
  "source": {
    object (Source)
  },
  "testSuite": {
    object (TestSuite)
  }
}
Campos
source

object ( Source )

Source a ser verificada quanto à exatidão.

testSuite

object ( TestSuite )

O TestSuite embutido a ser executado no Source .

Quando Source é fornecida inline, os casos de teste só serão executados se a Source for sintaticamente e semanticamente válida.

Corpo de resposta

Se for bem-sucedido, o corpo da resposta conterá dados com a seguinte estrutura:

A resposta para FirebaseRulesService.TestRuleset .

Representação JSON
{
  "issues": [
    {
      object (Issue)
    }
  ],
  "testResults": [
    {
      object (TestResult)
    }
  ]
}
Campos
issues[]

object ( Issue )

Problemas Source sintática e semântica de gravidade variável. Problemas de gravidade ERROR impedirão a execução dos testes.

testResults[]

object ( TestResult )

O conjunto de resultados de teste dados os casos de teste no TestSuite . Os resultados aparecerão na mesma ordem em que os casos de teste aparecem no TestSuite .

Escopos de autorização

Requer um dos seguintes escopos OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/firebase
  • https://www.googleapis.com/auth/firebase.readonly

Para obter mais informações, consulte Visão geral da autenticação .

Suíte de teste

TestSuite é uma coleção de instâncias TestCase que validam a correção lógica das regras. O TestSuite pode ser referenciado em linha em uma chamada projects.test ou como parte de um objeto Release como uma verificação de pré-lançamento.

Representação JSON
{
  "testCases": [
    {
      object (TestCase)
    }
  ]
}
Campos
testCases[]

object ( TestCase )

Coleção de casos de teste associados ao TestSuite .

Caso de teste

As mensagens TestCase fornecem o contexto da solicitação e uma expectativa sobre se o contexto fornecido será permitido ou negado. Os casos de teste podem especificar request , resosurce e functionMocks para simular uma chamada de função para uma função fornecida por serviço.

O objeto request representa o contexto presente no momento da solicitação.

O resource é o valor do recurso de destino (por exemplo, metadados de um objeto GCS ou documento do Firestore) conforme aparece no armazenamento persistente antes da execução da solicitação.

Consulte também a documentação de referência relacionada ao Cloud Firestore ( request , resource ) e Cloud Storage for Firebase ( request , resource ).

Representação JSON
{
  "expectation": enum (Expectation),
  "request": value,
  "resource": value,
  "functionMocks": [
    {
      object (FunctionMock)
    }
  ],
  "pathEncoding": enum (PathEncoding),
  "expressionReportLevel": enum (ExpressionReportLevel)
}
Campos
expectation

enum ( Expectation )

Expectativa de teste.

request

value ( Value format)

Contexto da solicitação.

O formato exato do contexto da solicitação depende do serviço. Consulte a documentação de serviço apropriada para obter informações sobre os campos e tipos suportados na solicitação. No mínimo, todos os serviços suportam os seguintes campos e tipos:

Campo de solicitação Tipo
autenticação.uid string
auth.token map<string, string>
cabeçalhos map<string, string>
método string
parâmetros map<string, string>
caminho string
tempo google.protobuf.Timestamp

Se o valor da solicitação não estiver bem formado para o serviço, a solicitação será rejeitada como um argumento inválido.

resource

value ( Value format)

Valor do recurso opcional conforme aparece no armazenamento persistente antes que a solicitação seja atendida.

O tipo de recurso depende do valor request.path .

functionMocks[]

object ( FunctionMock )

Simulações de funções de regras opcionais para funções definidas pelo serviço. Se não for definido, espera-se que qualquer função de regras definida pelo serviço retorne um erro, que pode ou não influenciar o resultado do teste.

pathEncoding

enum ( PathEncoding )

Especifica se os caminhos (como request.path) são codificados e como.

expressionReportLevel

enum ( ExpressionReportLevel )

Especifica o que deve ser incluído na resposta.

Expectativa

O conjunto de expectativas de casos de teste com suporte.

Enums
EXPECTATION_UNSPECIFIED Expectativa não especificada.
ALLOW Espere um resultado permitido.
DENY Espere um resultado negado.

FunçãoMock

Definição da função de regras simuladas.

Os mocks devem se referir a uma função declarada pelo serviço de destino. O tipo da função args e result será inferido no momento do teste. Se os valores arg ou result não forem compatíveis com a declaração do tipo de função, a solicitação será considerada inválida.

Mais de um FunctionMock pode ser fornecido para um determinado nome de função, desde que os correspondentes Arg sejam distintos. Pode haver apenas uma função para uma determinada sobrecarga onde todos os valores Arg são Arg.any_value .

Consulte também Funções na linguagem de regras de segurança .

Representação JSON
{
  "function": string,
  "args": [
    {
      object (Arg)
    }
  ],
  "result": {
    object (Result)
  }
}
Campos
function

string

O nome da função.

O nome da função deve corresponder ao fornecido por uma declaração de serviço.

args[]

object ( Arg )

A lista de valores Arg a serem correspondidos. A ordem em que os argumentos são fornecidos é a ordem em que devem aparecer na invocação da função.

result

object ( Result )

O resultado simulado da chamada de função.

Argumento

Correspondentes de argumentos para a função simulada.

Representação 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.
}
Campos
type de campo de união. Valores de argumentos suportados. type pode ser apenas um dos seguintes:
exactValue

value ( Value format)

O argumento corresponde exatamente ao valor fornecido.

anyValue

object

O argumento corresponde a qualquer valor fornecido.

Resultado

Valores de resultados possíveis da invocação simulada da função.

Representação 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.
}
Campos
type de campo de união. Valores de resultados suportados. type pode ser apenas um dos seguintes:
value

value ( Value format)

O resultado é um valor real. O tipo do valor deve corresponder ao tipo declarado pelo serviço.

undefined

object

O resultado é indefinido, o que significa que o resultado não pôde ser calculado.

codificação de caminho

O tipo de codificação de caminho usada.

Enums
ENCODING_UNSPECIFIED Nenhuma codificação foi especificada. O padrão é o comportamento "URL_ENCODED".
URL_ENCODED Trata segmentos de caminho como codificados em URL, mas com separadores não codificados ("/"). Este é o comportamento padrão.
PLAIN Trata o caminho total como não codificado por URL, por exemplo, bruto.

ExpressãoReportLevel

A quantidade de dados a incluir na resposta do relatório de expressão.

Enums
LEVEL_UNSPECIFIED Nenhum nível foi especificado. O padrão é o comportamento "NONE".
NONE Não inclua nenhuma informação adicional.
FULL Incluir relatórios detalhados sobre as expressões avaliadas.
VISITED Inclua apenas as expressões que foram visitadas durante a avaliação.

Emitir

Os problemas incluem avisos, erros e avisos de suspensão de uso.

Representação JSON
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "description": string,
  "severity": enum (Severity)
}
Campos
sourcePosition

object ( SourcePosition )

Posição do problema na Source .

description

string

Breve descrição do erro.

severity

enum ( Severity )

A gravidade do problema.

Posição de origem

Posição no conteúdo Source incluindo sua linha, número de coluna e um índice do File na mensagem Source . Usado para fins de depuração.

Representação JSON
{
  "fileName": string,
  "line": integer,
  "column": integer,
  "currentOffset": integer,
  "endOffset": integer
}
Campos
fileName

string

Nome do File .

line

integer

Número da linha do fragmento de origem. Baseado em 1.

column

integer

Primeira coluna na linha de origem associada ao fragmento de origem.

currentOffset

integer

Posição inicial relativa ao início do arquivo.

endOffset

integer

Posição final relativa ao início do arquivo.

Gravidade

O conjunto de gravidades do problema.

Enums
SEVERITY_UNSPECIFIED Uma gravidade não especificada.
DEPRECATION Problema de depreciação para instruções e métodos que não podem mais ser suportados ou mantidos.
WARNING Avisos como: variáveis ​​não utilizadas.
ERROR Erros como: chaves incomparáveis ​​ou redefinição de variáveis.

Resultado do teste

Mensagem de resultado de teste contendo o estado do teste, bem como uma descrição e posição de origem para falhas de teste.

Representação JSON
{
  "state": enum (State),
  "debugMessages": [
    string
  ],
  "errorPosition": {
    object (SourcePosition)
  },
  "functionCalls": [
    {
      object (FunctionCall)
    }
  ],
  "visitedExpressions": [
    {
      object (VisitedExpression)
    }
  ],
  "expressionReports": [
    {
      object (ExpressionReport)
    }
  ]
}
Campos
state

enum ( State )

Estado do teste.

debugMessages[]

string

Mensagens de depuração relacionadas a problemas de execução de teste encontrados durante a avaliação.

As mensagens de depuração podem estar relacionadas a muitas ou poucas invocações de simulações de função ou a erros de tempo de execução que ocorrem durante a avaliação.

Por exemplo: Unable to read variable [name: "resource"]

errorPosition

object ( SourcePosition )

Posição na Source onde ocorre o principal erro de tempo de execução.

A avaliação de uma expressão pode resultar em erro. As regras são negadas por padrão, portanto, uma expectativa DENY quando um erro é gerado é válida. Quando há um DENY com erro, o SourcePosition é retornado.

Por exemplo, errorPosition { line: 19 column: 37 }

functionCalls[]

object ( FunctionCall )

O conjunto de chamadas de função feitas para métodos definidos pelo serviço.

As chamadas de função são incluídas na ordem em que são encontradas durante a avaliação, são fornecidas para funções simuladas e não simuladas e incluídas na resposta, independentemente do state do teste.

visitedExpressions[]

object ( VisitedExpression )

O conjunto de expressões de permissão visitadas para um determinado teste. Isso retorna as posições e os resultados da avaliação de todas as expressões de permissão visitadas que foram relevantes para o caso de teste, por exemplo

match /path {
  allow read if: <expr>
}

Para um relatório detalhado dos estados de avaliação intermediários, consulte o campo expressionReports

expressionReports[]

object ( ExpressionReport )

O mapeamento da expressão no conjunto de regras AST para os valores para os quais foram avaliados. Parcialmente aninhado para espelhar a estrutura AST. Observe que este campo está, na verdade, rastreando expressões e não declarações de permissão, em contraste com o campo "visitedExpressions" acima. Expressões literais são omitidas.

Estado

Estados válidos para o resultado do teste.

Enums
STATE_UNSPECIFIED O estado de teste não está definido.
SUCCESS O teste é um sucesso.
FAILURE O teste é um fracasso.

FunçãoChamada

Representa uma chamada de função definida pelo serviço que foi invocada durante a execução do teste.

Representação JSON
{
  "function": string,
  "args": [
    value
  ]
}
Campos
function

string

Nome da função invocada.

args[]

value ( Value format)

Os argumentos que foram fornecidos à função.

Expressão visitada

Armazene a posição e o resultado do acesso para uma expressão visitada nas regras.

Representação JSON
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "value": value
}
Campos
sourcePosition

object ( SourcePosition )

Posição na Source onde uma expressão foi visitada.

value

value ( Value format)

O valor avaliado para a expressão visitada, por exemplo, verdadeiro/falso

Relatório de Expressão

Descreve onde uma expressão é encontrada em um arquivo e como ela foi avaliada ao longo de seu uso.

Representação JSON
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "values": [
    {
      object (ValueCount)
    }
  ],
  "children": [
    {
      object (ExpressionReport)
    }
  ]
}
Campos
sourcePosition

object ( SourcePosition )

Posição da expressão na fonte original das regras.

values[]

object ( ValueCount )

Valores que esta expressão avaliou quando encontrada.

children[]

object ( ExpressionReport )

Subexpressões

Contagem de valor

Tupla para quantas vezes uma Expressão foi avaliada para um ExpressionValue específico.

Representação JSON
{
  "value": value,
  "count": integer
}
Campos
value

value ( Value format)

O valor de retorno da expressão

count

integer

O número de vezes que essa expressão retornou.