Request matching

To define the conditions for matching request data in your mock service, you can utilize various operators. By choosing the appropriate operator, you can precisely specify what values the request data should have in order to be matched by the mock service.

  request: 
    header: <mapping> # optional
    body|stream: <mapping | sequence> # optional

gRPC method name matching

Every call in a gRPC mock config file should specify a gRPC method to match in the format <Package>.<Service>/<Method> where

Package is the name of a package specifier in your .proto file
Service is the name of a service in your .proto file
Method is the name of a gRPC service method

Example:

calls:
- method: greet.Greeter/SayHello

for a .proto file like this:

package greet;
service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

HTTP method and URL matching

Every call in a HTTP mock config file should specify a HTTP method and HTTP URL to match. Example:

calls:
- url: /index.html
  method: GET

A significant aspect of a URL parameter is the ability to use templating with URL Path and URL Query parameters:

# URL template, where "id" is a path parameter
# the parameter value is accessible in request matching and response templating expressions using scripting feature: {{ request.url_path.id }}
calls:
- url: /post/{id}
  method: GET

# You can use "request.url_path" to add matching rules for a particular url path parameter:
calls:
- url: /post/{id}
  method: GET
  request:
    url_path:
      id:
        matchesWildcard: "blog-*"
  response:
    body:
      field1: "{{ request.url_path.id }}"

# URL template, where "id" is a query parameter
# the parameter value is accessible in request matching and response templating expressions using scripting feature: {{ request.path_query.id }}
calls:
- url: /post?id={id}
  method: GET

# You can use "request.url_query" to add matching rules for a particular url query parameter:
calls:
- url: /post?id={id}
  method: GET
  request:
    url_query:
      id:
        matchesWildcard: "blog-*"
  response:
    body:
      field1: "{{ request.url_query.id }}"

# all together
calls:
- url: /post/{id}?lang={language}
  method: GET
  response:
    body:
      field1: "{{ request.url_path.id }}"
      field2: "{{ request.url_query.language }}"

Header matching

A header is treated as a mapping property with key-value pairs, so all property operators that work with request payloads also work with a header.

Examples:

  request:
    header:
      X-Custom-Attr: "Value"

  request:
    header:
      X-Custom-Attr:
        startWith: "Val"

  request:
    header:
      matchYamlFile: "/common-header.yml"

Property matching

Scalar property matching

Example:

# match a request where the "name" scalar property is equal to "Kelly""
  request:
    body:
      name: "Kelly"

Sequence property matching

Example:

# match a request where the "names" sequence property is equal to the array ["item1", "item2"]
  response:
    body:
      names:
        - "item1"
        - "item2"

Complex property matching

Example:

# match a request where the "data" complex property is equal to { id: 1, name: "item1" }
  response:
    body:
      data:
        id: 1
        name: "item1"

Matching operators

"not" operator

Inverts the result of an underlying operator.

Definition:

<property>:
  not: <scalar | sequence | mapping>

Example:

  request:
    header:
      Authorization:
        not:
          startsWith: Bearer

"and" operator

It is possible to apply multiple operators to the same property, and they will be combined using AND logic.

Example:

# means ("startsWith: Bearer" AND "endsWith: jwt signature")
  request:
    header:
      Authorization:
        startsWith: Bearer
        endsWith: .SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

equalTo

Matches only if the property value is exactly the same as the specified value.

Definition:

# short form
<property>: <scalar | sequence | mapping>

# long form
<property>:
  equalTo: <scalar | sequence | mapping>

Examples:

# short form
  request:
    body:
      name: "Kelly"

# long form
  request:
    body:
      name:
        equalTo:
          - "Kelly"

The operator supports sequence as an input parameter.

OR logic is applied If the underlying gRPC property type is scalar
AND logic is applied If the underlying gRPC property type is sequence

# name is a scalar property, means "(name == Kelly) OR (name == John)"
request:
    body:
      name: 
        equalTo:
          - "Kelly"
          - "John"

# names is a sequence property, means "names == [Kelly, John]"
  request:
    body:
      names:
        equalTo:
          - "Kelly"
          - "John"

equivalentTo

Matches a sequence property or a map property value without taking into account an order of items.

<property>:
  equivalentTo: <scalar | sequence | mapping>

lessThan

Matches if the number property value is less than the specified value;

<property>:
  lessThan: <scalar>

lessOrEqualTo

Matches if the number property value is less than or equal to the specified value;

<property>:
  lessOrEqualTo: <scalar>

moreThan

Matches if the number property value is more than the specified value;

<property>:
  moreThan: <scalar>

moreOrEqualTo

Matches if the number property value is more than or equal to the specified value;

<property>:
  moreOrEqualTo: <scalar>

contains

Matches if the property value contains the specified value

as a substring for a scalar property
as an item for a sequence or mapping property

Definition:

<property>:
  contains: <scalar | sequence | mapping>

  request:
    body:
      name:
        contains: "Kelly"

  request:
    body:
      names:
        contains:
          - "Kelly"

startsWith

Matches if the property value starts with the specified value or specified sequence.

Definition:

<property>:
  startsWith: <scalar | sequence | mapping>

Example:

  request:
    header:
      Authorization:
        startsWith: Bearer

endsWith

Matches if the property value ends with the specified value or specified sequence.

<property>:
  endsWith: <scalar | sequence | mapping>

matchesWildcard

Matches if the property value matches the specified wildcard pattern.

Definition:

<property>:
  matchesWildcard: <scalar>

Example:

  request:
    header:
      Authorization:
        matchesWildcard: "Bearer *"

matchesRegEx

Matches if the property value matches the specified regular expression.

Definition:

<property>:
  matchesRegEx: <scalar>

Example:

  request:
    header:
      Authorization:
        matchesRegEx: "Bearer .*"

matchesJPath

A match is determined by executing the JSON Path expression on the property value after it has been converted to JSON format. If the expression returns one or more nodes, the property is considered a match.

https://goessner.net/articles/JsonPath/

Definition:

<property>:
  matchesJPath: <scalar>

Example:

# matches a request with an array "arrayField" if it contains a property "stringField" that is equal to "Test StringField" 
  request:
    body:
      matchesJPath: "$.arrayField[?(@.stringField=='Test StringField')]"

matchesJsonFile

Matches if the property value is equal to the contents of the specified JSON file.

Note: YAML, JSON, and Protocol Buffer (protobuf) formats can be converted to one another and are considered equivalent.

<property>:
  matchesJsonFile: <fileName>

matchesYamlFile

Matches if the property value is equal to the contents of the specified YAML file.

Note: YAML, JSON, and Protocol Buffer (protobuf) formats can be converted to one another and are considered equivalent.

<property>:
  matchesYamlFile: <fileName>