Method: projects.test

Przetestuj działanie Source pod kątem poprawności składniowej i semantycznej. Istniejące problemy (jeśli jakieś występują) zostaną zwrócone do osoby wywołującej wraz z opisem, powagą i lokalizacją źródła.

Metodę testowania można wykonać za pomocą funkcji Source. Zaliczenie Source przydaje się do testowania jednostkowego nowych reguł.

Pamiętaj, że testy przeprowadzane za pomocą interfejsu API REST korzystają z produkcyjnych baz danych, zasobników na dane i powiązanych źródeł danych. Takie testy mogą powodować naliczanie opłat za korzystanie. Zdecydowanie zalecamy używanie Pakietu emulatorów lokalnych Firebase do testowania reguł, ponieważ testy można przeprowadzać na zasobach nieprodukcyjnych offline, bez opłat za wykorzystanie.

Oto przykład kodu Source, który umożliwia użytkownikom przesyłanie do zasobnika obrazów o odpowiednim identyfikatorze użytkownika i z poprawnymi metadanymi:

Przykład

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

Żądanie HTTP

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

Adres URL używa składni transkodowania gRPC.

Parametry ścieżki

Parametry
name

string

Wymagane. W przypadku testów pod kątem zgodności z zasadą source nazwa zasobu musi odnosić się do projektu: Format: projects/{project_id}

Treść żądania

Treść żądania zawiera dane o następującej strukturze:

Zapis JSON 
{
  "source": {
    object (Source)
  },
  "testSuite": {
    object (TestSuite)
  }
}
Pola
source

object (Source)

Source, aby sprawdzić poprawność.
testSuite

object (TestSuite)

Wbudowany kod TestSuite do wykonania w odniesieniu do Source.

Jeśli właściwość Source jest podana w tekście, przypadki testowe będą uruchamiane tylko wtedy, gdy parametr Source będzie poprawny składniowo i semantycznie.

Treść odpowiedzi

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

Odpowiedź dla: FirebaseRulesService.TestRuleset.

Zapis JSON 
{
  "issues": [
    {
      object (Issue)
    }
  ],
  "testResults": [
    {
      object (TestResult)
    }
  ]
}
Pola
issues[]

object (Issue)

Syntaktyczne i semantyczne problemy typu Source o różnym wadze. Wykonywanie testów nie będzie możliwe z problemami o poziomie ważności ERROR.
testResults[]

object (TestResult)

Zbiór wyników testów na podstawie przypadków testowych w: TestSuite. Wyniki pojawią się w tej samej kolejności, w jakiej znajdują się przypadki testowe w TestSuite.

Zakresy autoryzacji

Wymaga jednego z tych zakresów protokołu OAuth:

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

Więcej informacji znajdziesz w artykule o uwierzytelnianiu (w języku angielskim).

TestSuite

TestSuite to zbiór TestCase instancji, który weryfikuje logiczną prawidłowość reguł. Do obiektu TestSuite można się odwoływać w tekście w wywołaniu projects.test lub jako część obiektu Release w ramach kontroli przedpremierowej.

Zapis JSON 
{
  "testCases": [
    {
      object (TestCase)
    }
  ]
}
Pola
testCases[]

object (TestCase)

Zbiór przypadków testowych powiązanych z TestSuite.

Przypadek testowy

Komunikaty TestCase zawierają kontekst żądania i oczekiwanie, czy dany kontekst będzie dozwolony czy odrzucony. Przypadki testowe mogą określać request, resosurce i functionMocks w celu imitowania wywołania funkcji udostępnionej przez usługę.

Obiekt request reprezentuje kontekst w momencie żądania.

resource to wartość zasobu docelowego (np. metadane obiektu GCS lub dokumentu Firestore), która znajduje się w pamięci trwałej przed wykonaniem żądania.

Zapoznaj się też z dokumentacją Cloud Firestore ( żądanie, zasób) i Cloud Storage dla Firebase (żądanie oraz zasób).

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

enum (Expectation)

Oczekiwanie testu.
request

value (Value format)

Kontekst żądania.

Dokładny format kontekstu żądania zależy od usługi. Informacje na temat pól i typów obsługiwanych w żądaniu znajdziesz w odpowiedniej dokumentacji usługi. Minimalnie wszystkie usługi obsługują te pola i typy:

Pole żądania Typ
auth.uid string
token.auth.token map<string, string>
nagłówki map<string, string>
method string
parametry map<string, string>
ścieżka string
time. google.protobuf.Timestamp

Jeśli wartość żądania nie jest prawidłowo sformatowana w przypadku usługi, zostanie odrzucone jako nieprawidłowy argument.
resource

value (Value format)

Opcjonalna wartość zasobu widoczna w pamięci trwałej przed zrealizowaniem żądania.

Typ zasobu zależy od wartości request.path.
functionMocks[]

object (FunctionMock)

Funkcja reguł opcjonalnych ma przykłady funkcji zdefiniowanych przez usługę. Jeśli jej nie skonfigurujesz, każda funkcja zdefiniowana przez usługę reguł powinna zwracać błąd, który może wpłynąć na wynik testu, ale nie musi.
pathEncoding

enum (PathEncoding)

Określa, czy ścieżki (np. request.path) są kodowane i w jaki sposób.
expressionReportLevel

enum (ExpressionReportLevel)

Określa, co ma zawierać odpowiedź.

Oczekiwanie

Zbiór oczekiwań na potrzeby przypadku testowego.

Wartości w polu enum
EXPECTATION_UNSPECIFIED Nieokreślone oczekiwanie.
ALLOW Spodziewaj się dozwolonego wyniku.
DENY Oczekiwany jest odrzucony wynik.

Przykładowy szablon funkcji

Definicja funkcji przykładowych reguł.

Przykłady muszą odnosić się do funkcji zadeklarowanej przez usługę docelową. Typ argumentów funkcji i wynik zostanie ustalony w czasie testu. Jeśli wartości argumentu lub wyników nie są zgodne z deklaracją typu funkcji, żądanie zostanie uznane za nieprawidłowe.

Dla danej nazwy funkcji można podać więcej niż jeden element FunctionMock, o ile dopasowania typu Arg są różne. W przypadku danego przeciążenia może istnieć tylko 1 funkcja, przy czym wszystkie wartości Arg to Arg.any_value.

Zobacz też Funkcje w języku reguł zabezpieczeń.

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

string

Nazwa funkcji.

Nazwa funkcji musi być zgodna z nazwą w deklaracji usługi.
args[]

object (Arg)

Lista Arg wartości do dopasowania. Kolejność, w jakiej podawane są argumenty, odpowiada kolejności ich występowania w wywołaniu funkcji.
result

object (Result)

Przykładowy wynik wywołania funkcji.

arg

Dopasowania argumentów dla funkcji pozornej.

Zapis 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.
}
Pola
Pole sumy type. Obsługiwane wartości argumentów. type może mieć tylko jedną z tych wartości:
exactValue

value (Value format)

Argument ściśle pasuje do podanej wartości.
anyValue

object

Argument jest zgodny z dowolną podaną wartością.

Wynik

Możliwe wartości wyników z pozornego wywołania funkcji.

Zapis 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.
}
Pola
Pole sumy type. Obsługiwane wartości wyników. type może mieć tylko jedną z tych wartości:
value

value (Value format)

Wynikiem jest rzeczywista wartość. Typ wartości musi być zgodny z typem zadeklarowanym przez usługę.
undefined

object

Wynik jest niezdefiniowany, co oznacza, że nie można go obliczyć.

Kodowanie PathEncoding

Typ użytego kodowania ścieżki.

Wartości w polu enum
ENCODING_UNSPECIFIED Kodowanie nie zostało określone. Domyślna wartość to „URL_ENCODED” zachowanie użytkownika.
URL_ENCODED Traktuje segmenty ścieżki jako zakodowane w adresie URL, ale z niezakodowanymi separatorami („/”). Jest to jego ustawienie domyślne.
PLAIN Traktuje łączną ścieżkę jako niezakodowaną adresem URL, np. nieprzetworzone.

Poziom_raportu_wyrażeń

Ilość danych do uwzględnienia w odpowiedzi na raport o wyrażeniach.

Wartości w polu enum
LEVEL_UNSPECIFIED Nie określono poziomu. Domyślna wartość to „NONE” zachowanie użytkownika.
NONE Nie podawaj żadnych dodatkowych informacji.
FULL Dołącz szczegółowe raporty na temat ocenianych wyrażeń.
VISITED Uwzględniaj tylko wyrażenia, które zostały odwiedzone podczas oceny.

Problem

Mogą to być ostrzeżenia, błędy i powiadomienia o wycofaniu.

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

object (SourcePosition)

Pozycja problemu w Source.
description

string

Krótki opis błędu.
severity

enum (Severity)

Waga problemu.

Pozycja źródłowa

Pozycja w treści Source, w tym jej wiersz, numer kolumny oraz indeks elementu File w komunikacie Source. Służy do debugowania.

Zapis JSON 
{
  "fileName": string,
  "line": integer,
  "column": integer,
  "currentOffset": integer,
  "endOffset": integer
}
Pola
fileName

string

Nazwa elementu (File).
line

integer

Numer wiersza fragmentu źródłowego. 1,
column

integer

Pierwsza kolumna w wierszu źródłowym powiązanym z fragmentem źródłowym.
currentOffset

integer

Pozycja początkowa względem początku pliku.
endOffset

integer

Pozycja końcowa względem początku pliku.

Poziom ważności

Zestaw wagi problemów.

Wartości w polu enum
SEVERITY_UNSPECIFIED Nieokreślona ważność.
DEPRECATION Problem z wycofaniem instrukcji i metod, które mogą nie być już obsługiwane lub obsługiwane.
WARNING Ostrzeżenia, np.: nieużywane zmienne.
ERROR błędy, np. niedopasowane nawiasy klamrowe lub zmiany definicji zmiennych.

TestResult

Komunikat o wyniku testu zawierający stan testu, opis i pozycję źródłową w przypadku niepowodzenia testu.

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

enum (State)

Stan testu.
debugMessages[]

string

Komunikaty o debugowaniu związane z problemami z wykonaniem testu, które wystąpiły podczas oceny.

Komunikaty o debugowaniu mogą być związane ze zbyt dużą liczbą lub zbyt małą liczbą wywołań funkcji próbnych albo z błędami czasu działania występującymi podczas oceny.

Na przykład: Unable to read variable [name: "resource"]
errorPosition

object (SourcePosition)

Pozycja w tabeli Source, w której występuje podstawowy błąd czasu działania.

Ocena wyrażenia może zakończyć się błędem. Reguły są domyślnie odrzucane, więc prawidłowe jest oczekiwanie typu DENY w przypadku wygenerowania błędu. Gdy wystąpi błąd (DENY), zwracana jest wartość SourcePosition.

Na przykład: errorPosition { line: 19 column: 37 }
functionCalls[]

object (FunctionCall)

Zbiór wywołań funkcji wykonanych do metod zdefiniowanych przez usługę.

Wywołania funkcji są uwzględniane w kolejności, w jakiej występują podczas oceny, są podawane zarówno w przypadku funkcji próbnych, jak i nietestowanych. Są one uwzględniane w odpowiedzi niezależnie od testu state.
visitedExpressions[]

object (VisitedExpression)

Zbiór wyrażeń używanych do danego testu, które zostały odwiedzone przez użytkownika. Zwraca pozycje i wyniki oceny wszystkich odwiedzonych wyrażeń uprawnień, które były istotne w przypadku testu, np.

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

Szczegółowy raport o stanach oceny pośredniej znajdziesz w polu expressionReports
expressionReports[]

object (ExpressionReport)

Mapowanie z wyrażenia w zestawie reguł AST na wartości, na które zostały przeliczone. Częściowo zagnieżdżone, aby odzwierciedlić strukturę AST. Zwróć uwagę, że to pole śledzi wyrażenia, a nie instrukcje uprawnień (w odróżnieniu od pola „visitedExpressions”) powyżej. Wyrażenia dosłowne są pomijane.

Stan

Prawidłowe stany wyniku testu.

Wartości w polu enum
STATE_UNSPECIFIED Nie ustawiono stanu testu.
SUCCESS Testy kończą się sukcesem.
FAILURE Test kończy się niepowodzeniem.

Wywołanie funkcji

Reprezentuje wywołanie funkcji zdefiniowanej przez usługę, które zostało wywołane podczas wykonywania testu.

Zapis JSON 
{
  "function": string,
  "args": [
    value
  ]
}
Pola
function

string

Nazwa wywołanej funkcji.
args[]

value (Value format)

Argumenty podane dla funkcji.

VisitedExpression

Przechowuje pozycję i wynik dostępu dla wyrażenia odwiedzonego w regułach.

Zapis JSON 
{
  "sourcePosition": {
    object (SourcePosition)
  },
  "value": value
}
Pola
sourcePosition

object (SourcePosition)

Pozycja w tabeli Source, w której odwiedzono wyrażenie.
value

value (Value format)

Wartość obliczona dla odwiedzonego wyrażenia, np. prawda/fałsz

RaportWyrażenia

Opisuje, gdzie w pliku znajduje się wyrażenie i co zostało ocenione podczas jego użycia.

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

object (SourcePosition)

Pozycja wyrażenia w źródle reguł oryginalnych.
values[]

object (ValueCount)

Wartości, na które wyrażenie oceniło to wyrażenie.
children[]

object (ExpressionReport)

Wyrażenia podrzędne

Liczba wartości

Kropka określająca, ile razy wyrażenie zostało ocenione jako określona wartość wyrażenia.

Zapis JSON 
{
  "value": value,
  "count": integer
}
Pola
value

value (Value format)

Wartość zwrócona wyrażenia
count

integer

Liczba wystąpień tego wyrażenia.