Method: projects.test

Testare la correttezza sintattica e semantica Source . I problemi presenti, se presenti, verranno restituiti al chiamante con una descrizione, gravità e posizione di origine.

Il metodo di test può essere eseguito con Source . Passare Source è utile per testare unità di nuove regole.

Tieni presente che i test eseguiti utilizzando l'API REST utilizzano database di produzione, bucket di archiviazione e risorse rse correlate. Tali test possono comportare costi di utilizzo. Ti consigliamo vivamente di utilizzare Firebase Local Emulator Suite per eseguire test delle regole, poiché puoi eseguire test su risorse offline non di produzione senza costi di utilizzo.

Quello che segue è un esempio di Source che consente agli utenti di caricare immagini in un bucket recante il proprio ID utente e corrispondente ai metadati corretti:

Esempio

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

Richiesta HTTP

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

L'URL usa la sintassi di transcodifica gRPC .

Parametri del percorso

Parametri
name

string

Necessario. Per i test su source , il nome della risorsa deve fare riferimento al progetto: Formato: projects/{project_id}

Richiedi corpo

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON
{
  "source": {
    object (Source)
  },
  "testSuite": {
    object (TestSuite)
  }
}
Campi
source

object ( Source )

Source da verificare per correttezza.

testSuite

object ( TestSuite )

La TestSuite inline da eseguire rispetto al Source .

Quando Source viene fornito in linea, i test case verranno eseguiti solo se Source è sintatticamente e semanticamente valido.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

La risposta per FirebaseRulesService.TestRuleset .

Rappresentazione JSON
{
  "issues": [
    {
      object (Issue)
    }
  ],
  "testResults": [
    {
      object (TestResult)
    }
  ]
}
Campi
issues[]

object ( Issue )

Problemi Source sintattica e semantica di varia gravità. Problemi di gravità ERROR impediranno l'esecuzione dei test.

testResults[]

object ( TestResult )

L'insieme dei risultati dei test forniti dai casi di test nella TestSuite . I risultati appariranno nello stesso ordine in cui i casi di test appaiono in TestSuite .

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, vedere la panoramica sull'autenticazione .

Test Suite

TestSuite è una raccolta di istanze TestCase che convalidano la correttezza logica delle regole. È possibile fare riferimento a TestSuite in linea all'interno di un'invocazione projects.test o come parte di un oggetto Release come controllo pre-rilascio.

Rappresentazione JSON
{
  "testCases": [
    {
      object (TestCase)
    }
  ]
}
Campi
testCases[]

object ( TestCase )

Raccolta di casi di test associati a TestSuite .

Caso di prova

I messaggi TestCase forniscono il contesto della richiesta e un'aspettativa se il contesto specificato verrà consentito o negato. I casi di test possono specificare request , resosurce e functionMocks per simulare una chiamata di funzione a una funzione fornita dal servizio.

L'oggetto request rappresenta il contesto presente al momento della richiesta.

La resource è il valore della risorsa di destinazione (ad esempio, i metadati di un oggetto GCS o un documento Firestore) come appare nell'archivio persistente prima che la richiesta venga eseguita.

Consulta anche la documentazione di riferimento correlata per Cloud Firestore ( richiesta , risorsa ) e Cloud Storage for Firebase ( richiesta , risorsa ).

Rappresentazione JSON
{
  "expectation": enum (Expectation),
  "request": value,
  "resource": value,
  "functionMocks": [
    {
      object (FunctionMock)
    }
  ],
  "pathEncoding": enum (PathEncoding),
  "expressionReportLevel": enum (ExpressionReportLevel)
}
Campi
expectation

enum ( Expectation )

Prova aspettativa.

request

value ( Value format)

Richiedi contesto.

Il formato esatto del contesto della richiesta dipende dal servizio. Consulta la documentazione del servizio appropriata per informazioni sui campi e sui tipi supportati nella richiesta. Come minimo, tutti i servizi supportano i seguenti campi e tipi:

Campo richiesta Tipo
auth.uid string
token.auth map<string, string>
intestazioni map<string, string>
metodo string
parametri map<string, string>
sentiero string
tempo google.protobuf.Timestamp

Se il valore della richiesta non è formato correttamente per il servizio, la richiesta verrà rifiutata come argomento non valido.

resource

value ( Value format)

Valore della risorsa facoltativo come appare nell'archivio permanente prima che la richiesta venga soddisfatta.

Il tipo di risorsa dipende dal valore request.path .

functionMocks[]

object ( FunctionMock )

La funzione Regole facoltative simula le funzioni definite dal servizio. Se non impostata, è previsto che qualsiasi funzione delle regole definita dal servizio restituisca un errore, che potrebbe influenzare o meno il risultato del test.

pathEncoding

enum ( PathEncoding )

Specifica se i percorsi (come request.path) sono codificati e come.

expressionReportLevel

enum ( ExpressionReportLevel )

Specifica cosa deve essere incluso nella risposta.

Aspettativa

L'insieme delle aspettative dei test case supportate.

Enumerazioni
EXPECTATION_UNSPECIFIED Aspettativa non specificata.
ALLOW Aspettatevi un risultato consentito.
DENY Aspettatevi un risultato negato.

FunzioneMock

Definizione della funzione Mock Rules.

I mock devono fare riferimento a una funzione dichiarata dal servizio di destinazione. Il tipo degli argomenti e del risultato della funzione verranno dedotti al momento del test. Se i valori dell'argomento o dei risultati non sono compatibili con la dichiarazione del tipo di funzione, la richiesta verrà considerata non valida.

È possibile fornire più di un FunctionMock per un determinato nome di funzione purché i corrispondenti Arg siano distinti. Potrebbe esserci una sola funzione per un determinato sovraccarico in cui tutti i valori Arg sono Arg.any_value .

Vedi anche Funzioni nel linguaggio Regole di sicurezza .

Rappresentazione JSON
{
  "function": string,
  "args": [
    {
      object (Arg)
    }
  ],
  "result": {
    object (Result)
  }
}
Campi
function

string

Il nome della funzione.

Il nome della funzione deve corrispondere a quello fornito da una dichiarazione di servizio.

args[]

object ( Arg )

L'elenco dei valori Arg da abbinare. L'ordine in cui vengono forniti gli argomenti è l'ordine in cui devono apparire nell'invocazione della funzione.

result

object ( Result )

Il risultato fittizio della chiamata di funzione.

Arg

Corrispondenze Arg per la funzione mock.

Rappresentazione 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.
}
Campi
type di campo Unione. Valori degli argomenti supportati. type può essere solo uno dei seguenti:
exactValue

value ( Value format)

L'argomento corrisponde esattamente al valore fornito.

anyValue

object

L'argomento corrisponde a qualsiasi valore fornito.

Risultato

Possibili valori di risultato dall'invocazione simulata della funzione.

Rappresentazione 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.
}
Campi
type di campo Unione. Valori dei risultati supportati. type può essere solo uno dei seguenti:
value

value ( Value format)

Il risultato è un valore reale. Il tipo del valore deve corrispondere a quello del tipo dichiarato dal servizio.

undefined

object

Il risultato non è definito, ovvero non è stato possibile calcolarlo.

PathEncoding

Il tipo di codifica del percorso utilizzata.

Enumerazioni
ENCODING_UNSPECIFIED Non è stata specificata alcuna codifica. Per impostazione predefinita il comportamento è "URL_ENCODED".
URL_ENCODED Tratta i segmenti del percorso come URL codificati ma con separatori non codificati ("/"). Questo è il comportamento predefinito.
PLAIN Tratta il percorso totale come codificato non URL, ad esempio non elaborato.

ExpressionReportLevel

La quantità di dati da includere nella risposta del report dell'espressione.

Enumerazioni
LEVEL_UNSPECIFIED Non è stato specificato alcun livello. Per impostazione predefinita il comportamento è "NESSUNO".
NONE Non includere alcuna informazione aggiuntiva.
FULL Includere report dettagliati sulle espressioni valutate.
VISITED Includere solo le espressioni visitate durante la valutazione.

Problema

I problemi includono avvisi, errori e avvisi di deprecazione.

Rappresentazione JSON
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "description": string,
  "severity": enum (Severity)
}
Campi
sourcePosition

object ( SourcePosition )

Posizione del problema nella Source .

description

string

Breve descrizione dell'errore.

severity

enum ( Severity )

La gravità del problema.

Posizione origine

Posizione nel contenuto Source inclusa la riga, il numero di colonna e un indice del File nel messaggio Source . Utilizzato per scopi di debug.

Rappresentazione JSON
{
  "fileName": string,
  "line": integer,
  "column": integer,
  "currentOffset": integer,
  "endOffset": integer
}
Campi
fileName

string

Nome del File .

line

integer

Numero di riga del frammento di origine. 1 in base.

column

integer

Prima colonna sulla riga di origine associata al frammento di origine.

currentOffset

integer

Posizione iniziale relativa all'inizio del file.

endOffset

integer

Posizione finale rispetto all'inizio del file.

Gravità

L'insieme delle gravità dei problemi.

Enumerazioni
SEVERITY_UNSPECIFIED Una gravità non specificata.
DEPRECATION Problema di deprecazione per istruzioni e metodi che potrebbero non essere più supportati o mantenuti.
WARNING Avvertenze come: variabili non utilizzate.
ERROR Errori come: parentesi graffe non corrispondenti o ridefinizione delle variabili.

Risultato del test

Messaggio del risultato del test contenente lo stato del test, nonché una descrizione e la posizione di origine per i fallimenti del test.

Rappresentazione JSON
{
  "state": enum (State),
  "debugMessages": [
    string
  ],
  "errorPosition": {
    object (SourcePosition)
  },
  "functionCalls": [
    {
      object (FunctionCall)
    }
  ],
  "visitedExpressions": [
    {
      object (VisitedExpression)
    }
  ],
  "expressionReports": [
    {
      object (ExpressionReport)
    }
  ]
}
Campi
state

enum ( State )

Stato della prova.

debugMessages[]

string

Messaggi di debug relativi ai problemi di esecuzione del test riscontrati durante la valutazione.

I messaggi di debug possono essere correlati a troppe o troppo poche invocazioni di simulazioni di funzioni o a errori di runtime che si verificano durante la valutazione.

Ad esempio: Unable to read variable [name: "resource"]

errorPosition

object ( SourcePosition )

Posizione Source in cui si verifica l'errore di runtime principale.

La valutazione di un'espressione può causare un errore. Le regole sono negate per impostazione predefinita, quindi un'aspettativa DENY quando viene generato un errore è valida. Quando è presente un DENY con un errore, viene restituita la SourcePosition .

Ad esempio, errorPosition { line: 19 column: 37 }

functionCalls[]

object ( FunctionCall )

L'insieme di chiamate di funzione effettuate ai metodi definiti dal servizio.

Le chiamate di funzione sono incluse nell'ordine in cui vengono incontrate durante la valutazione, sono fornite sia per le funzioni mock che per quelle non mock e sono incluse nella risposta indipendentemente dallo state del test.

visitedExpressions[]

object ( VisitedExpression )

L'insieme delle espressioni di autorizzazione visitate per un determinato test. Ciò restituisce le posizioni e i risultati della valutazione di tutte le espressioni di autorizzazione visitate che erano rilevanti per il caso di test, ad es

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

Per un report dettagliato degli stati di valutazione intermedi, vedere il campo expressionReports

expressionReports[]

object ( ExpressionReport )

La mappatura dall'espressione nel set di regole AST ai valori in base ai quali sono stati valutati. Parzialmente nidificato per rispecchiare la struttura AST. Tieni presente che questo campo tiene effettivamente traccia delle espressioni e non delle dichiarazioni di autorizzazione, a differenza del campo "visitedExpressions" sopra. Le espressioni letterali vengono omesse.

Stato

Stati validi per il risultato del test.

Enumerazioni
STATE_UNSPECIFIED Lo stato del test non è impostato.
SUCCESS Il test è un successo.
FAILURE Il test è un fallimento.

FunzioneChiamata

Rappresenta una chiamata di funzione definita dal servizio che è stata richiamata durante l'esecuzione del test.

Rappresentazione JSON
{
  "function": string,
  "args": [
    value
  ]
}
Campi
function

string

Nome della funzione invocata.

args[]

value ( Value format)

Gli argomenti forniti alla funzione.

Espressione visitata

Memorizza la posizione e il risultato dell'accesso per un'espressione visitata nelle regole.

Rappresentazione JSON
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "value": value
}
Campi
sourcePosition

object ( SourcePosition )

Posizione nella Source in cui è stata visitata un'espressione.

value

value ( Value format)

Il valore valutato per l'espressione visitata, ad esempio vero/falso

Rapporto sull'espressione

Descrive dove si trova un'espressione in un file e cosa è stata valutata nel corso del suo utilizzo.

Rappresentazione JSON
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "values": [
    {
      object (ValueCount)
    }
  ],
  "children": [
    {
      object (ExpressionReport)
    }
  ]
}
Campi
sourcePosition

object ( SourcePosition )

Posizione dell'espressione nella fonte delle regole originali.

values[]

object ( ValueCount )

Valori valutati da questa espressione quando incontrati.

children[]

object ( ExpressionReport )

Sottoespressioni

Conteggiovalori

Tupla per il numero di volte in cui un'espressione è stata valutata rispetto a un particolare ExpressionValue.

Rappresentazione JSON
{
  "value": value,
  "count": integer
}
Campi
value

value ( Value format)

Il valore restituito dell'espressione

count

integer

Il numero di volte in cui l'espressione è stata restituita.