Scripting language
Introduction
The scripting language enables you to utilize request data, and the current date, and perform calculations, and transformations. It is a crucial and powerful aspect of a modern mock service. The language is similar to liquid templates by Shopify. Please note, that the YAML config file itself does not support liquid
templates. The evaluation of a template is limited to a YAML value expression only, which is enclosed in parentheses. The config must remain a valid YAML.
Valid, supported example:
# Good: the liquid expression is enclosed into parentheses
- method: greet.Greeter/SayHello
response:
header:
Expires: "{{ date.now | date.to_string '%a, %d %b %Y %T %Z' }}"
Invalid, not supported example:
# Bad: the liquid expression outside YAML value breaks YAML file format
- method: greet.Greeter/SayHello
response:
{{ if date.now.day == 1 }}
header:
Expires: "{{ date.now | date.to_string '%a, %d %b %Y %T %Z' }}"
{{ end }}
Scriban
The scripting is powered by Scriban project by Alexandre Mutel. Scriban is a fast, powerful, safe, and lightweight scripting language and engine for .NET, which was primarily developed for text templating with a compatibility mode for parsing liquid
templates.
- Full featured language including
if
/else
/for
/while
, expressions (x = 1 + 2
), conditions... etc. - Function calls and pipes (
myvar | string.capitalize
) - Complex objects (javascript/json like objects) and arrays (e.g
x = [1,2,3,4]
) - Built-in functions for working with
arrays
,date
,maths
,string
, etc
Developer documentation
- See the Language document for a description of the language syntax.
- See the Built-in functions document for the list of the built-in functions.
Build-in variables
request
request.url_path
Contains URL path parameters, can be used both in request and response sections.
Visibility:
- request.header
- request.body
- response.*
Example:
- url: /post/{id}
response:
body:
message: "id: {{ request.url_path.id }}"
status: OK
request.url_query
Contains URL query parameters, can be used both in request and response sections.
Visibility:
- request.header
- request.body
- response.*
Example:
- url: /post?id={id}
response:
body:
message: "id: {{ request.url_query.id }}"
status: OK
request.header
request.header
is a key-value map that represents an HTTP header of an incoming request. The key names for the header are converted to snake_case, for example X-Correlation-Id
becomes x_correlation_id
.
Visibility:
- request.header
- request.body
- response.*
Example:
- method: greet.Greeter/SayHello
response:
body:
message: "{{ request.header.content_type }}"
status: OK
Response:
{
"message": "application/grpc"
}
request.body
gRPC and HTTP request properties are accessible via request.body
variable. A gRPC object property can be accessed by its original name or by lowerCamelCase name.
Visibility:
- request.body
- response.*
Example:
- method: greet.Greeter/SayHello
response:
body:
message: "Hello {{ request.body.name }}!"
status: OK
Request:
{
"name": "Joe"
}
Response:
{
"message": "Hello Joe!"
}
response
response.header
response.header
is a key-value map that represents an HTTP header of an outgoing request. You can access response header fields using snake_case names, for example x-my-key
becomes x_my_key
.
Visibility:
- response.*
Example:
- method: greet.Greeter/SayHello
response:
header:
"x-my-key": "value"
body:
message: "Header value is {{ request.header.x_my_key }}!"
status: OK
response.body
gRPC and HTTP response properties are accessible via response.body
variable. A gRPC object property can be accessed by its original name or by lowerCamelCase name.
Visibility:
- response.body
- response.trailer
Example:
- method: package.Service/Method
response:
body:
first_name: "{{ faker.name.first_name }}"
last_name: "{{ faker.name.last_name }}"
full_name: "{{ response.body.first_name }} {{ response.body.last_name }}"
status: OK
response.trailer
You can access response trailer fields using snake_case names, for example x-my-key
becomes x_my_key
.
Visibility:
- response.trailer
Example:
- method: greet.Greeter/SayHello
response:
body:
message: "OK"
trailer:
"x-status": "OK"
checksum: "{{ response.trailer. }}"
status: OK
faker
Mock.qa provides a data faker that generates realistic data in responses for testing needs. There is a separate documentation article for Data generation, generation of an arbitrary field.
Visibility:
- request.*
- response.*
Example:
- url: /GetAllUsers
method: GET
response:
header:
"X-Correlation-Id": "{{ faker.random.guid }}"
body:
users:
repeat:
count: "{{ faker.random.number 2 10 }}"
item:
id: "{{ repeat.index }}"
firstName: "{{ faker.name.first_name female }}"
lastName: "{{ faker.name.last_name female }}"
fullName: "{{ repeat.item.firstName }} {{ repeat.item.lastName }}"
login: "{{ faker.internet.user_name repeat.item.firstName repeat.item.lastName }}"
email: "{{ faker.internet.email repeat.item.firstName repeat.item.lastName }}"
avatar: "{{ faker.internet.avatar }}"
balance: "{{ faker.finance.amount }}"
status: OK