Mockoon templating helpers

In addition to Handlebars' built-in helpers (if, each, etc., for more information, please have a look at Handlebars' documentation), Mockoon offers the following helpers:

 repeat

Repeat the block content a random number of times if two arguments are provided, or a fixed amount of time if only one argument is provided. Set the comma parameter to false (default to true) to prevent the insertion of new lines and commas by the helper.

Examples

Copy
{{#repeat 5 10 comma=true}}test{{/repeat}}

<!-- 
result: 
test,
test,
test,
test,
test -->

 switch

Select some content depending on a variable. Behaves like a regular switch.

Examples

Copy
{{#switch (urlParam 'id')}}
  {{#case '1'}}"John"{{/case}}
  {{#case '2'}}"Jack"{{/case}}
  {{#default}}"Peter"{{/default}}
{{/switch}}

 data

Get the stringified value at a given path from a data bucket selected by ID or name. This helper is designed to retrieve data to be served in a response. To reuse the retrieved data with other helpers (each, if, etc.), use the dataRaw helper below.

• The path supports two syntaxes, object-path or JSONPath Plus. When using object-path, properties containing dots are supported by escaping the dots: key.key\.with\.dot.
  Please note that a value can be retrieved at the path if the data bucket contains valid JSON.
• Full objects or arrays can be retrieved by the helper and will be stringified.
• The full data bucket content can be fetched when the path is omitted ({{data 'ID'}}).

Examples

Copy
{{data 'bucketNameOrId'}}

<!-- Using object-path syntax -->
{{data 'bucketNameOrId' 'path.to.property'}}
{{data 'bucketNameOrId' 'deep.property\.with\.dot'}}

<!-- using JSONPath syntax -->
{{data 'bucketNameOrId' '$.array.[*].property'}}

 dataRaw

Get the raw value (array, object, etc.) at a given path from a data bucket selected by ID or name. This "raw" helper is designed to work with other helpers (each, if, etc.). To directly use the retrieved data in the response, use data buckets direct linking or the data helper above.

• The path supports two syntaxes, object-path or JSONPath Plus. When using object-path, properties containing dots are supported by escaping the dots: key.key\.with\.dot.
  Please note that a value can be retrieved at the path if the data bucket contains valid JSON.
• Primitives and data structures can be retrieved by the helper and reused in other helpers (see example below).
• The full data bucket content (array, object, etc.) can be fetched when the path is omitted ({{dataRaw 'ID'}}).

Examples

Copy
{{dataRaw 'bucketNameOrId'}}

<!-- Using object-path syntax -->
{{dataRaw 'bucketNameOrId' 'path.to.property'}}
{{dataRaw 'bucketNameOrId' 'deep.property\.with\.dot'}}

<!-- using JSONPath syntax -->
{{dataRaw 'bucketNameOrId' '$.array.[*].property'}}

{{#each (dataRaw 'bucketNameOrId' 'path.to.array.property')}}
  value
{{/each}}

{{#if (dataRaw 'bucketNameOrId' 'path.to.boolean.property')}}
  value
{{/if}}

 setData

Set or modify the value at a given path in a data bucket selected by ID or name. This helper can perform various operations such as setting, pushing, deleting, incrementing, decrementing, and inverting values.

• The path supports the object-path syntax. When using object-path, properties containing dots are supported by escaping the dots: key.key\.with\.dot.
  Please note that a value can be set at the path if the data bucket contains valid JSON.
• The full data bucket content (array, object, etc.) can be modified when the path is omitted ({{setData 'operation' 'ID' '' 'value'}}).
• Available operations are set, push, del, inc, dec, and invert:
  • set: Set a new value at the root level (path omitted) or at the specified path. Requires a new value.
  • merge: If the value at the specified path is an object, merge the new value with the existing one. Requires a new value of type object.
  • push: Push a new value to an array at the root level (path omitted) or at the specified path. Requires a new value and the target to be an array.
  • del: Delete a value at the root level (path omitted) or at the specified path. No new value required.
  • inc: Increment a number at the root level (path omitted) or at the specified path. Requires a number to increment by. If the value is omitted, the increment will be by 1.
  • dec: Decrement a number at the root level (path omitted) or at the specified path. Requires a number to decrement by. If the value is omitted, the decrement will be by 1.
  • invert: Invert a boolean at the root level (path omitted) or at the specified path. No new value required.

Examples

Copy
{{setData 'set' 'bucketNameOrId' 'path.to.property' 'newValue'}}
<!-- Add a property to the target object -->
{{setData 'merge' 'bucketNameOrId' 'path.to.property' (object key='value')}}
<!-- Merge the target object with the request's body -->
{{setData 'merge' 'bucketNameOrId' 'path.to.property' (bodyRaw)}}
{{setData 'push' 'bucketNameOrId' 'path.to.array' 'newValue'}}
{{setData 'del' 'bucketNameOrId' 'path.to.property'}}
{{setData 'inc' 'bucketNameOrId' 'path.to.property' 2}}
{{setData 'dec' 'bucketNameOrId' 'path.to.property' 2}}
{{setData 'invert' 'bucketNameOrId' 'path.to.property'}}

 array

Create an array from the given items. This helper is mostly used with the following helpers: oneOf, someOf.

Examples

Copy
{{array 'item1' 'item2' 'item3'}}

 oneOf

Select a random item in the array passed in parameters. oneOf will return the actual value in the array. Set the stringify parameter to true (default to false) to get a JSON stringified result.

Examples

Copy
{{oneOf (array 'item1' 'item2' 'item3')}}
result: item2

 someOf

Return an array containing a random number of items from the array passed in parameters, eventually stringified. Use it with triple curly braces to get a non-escaped JSON representation.

Examples

Copy
{{someOf (array 'item1' 'item2' 'item3') 1 2}}
result: item1,item2

<!-- Use triple curly braces to avoid Handlebars' character escaping -->
{{{someOf (array 'item1' 'item2' 'item3') x y true}}}
result: ["item1","item2"]

 join

Return a new string by concatenating all the elements in an array.

Examples

Copy
{{join (array 'item1' 'item2' 'item3') '#'}}
result: item1#item2#item3

 slice

Return a copy of a portion of an array from start to end indexes (not included).

Examples

Copy
{{slice (array 'item1' 'item2' 'item3') 0 2}}
result: ['item1', 'item2']

 len

Return an array or string length.

Examples

Copy
{{len (array 'item1' 'item2' 'item3')}}
result: 3

{{len 'hello'}}
result: 5

 filter

Return a filtered array. This helper can be used with data buckets, use the dataRaw for that.

• The first argument is the array to be filtered.
• Each argument starting from index 1 is a condition filter (array 1 2 3) 1 3 5 6 .....
  • Condition can be primitives (string, number), objects or arrays with sub-conditions.
  • When the condition is an object, then all keys and values work as an AND.
  • Conditions support infinite nesting of conditions using arrays.
  • The first level of filer arguments works as OR conditions filter (array 1 2 3) 1 3 equals fo [1,2,3].filter(x => x === 3 || x === 1).
  • The second level of conditions works as AND sub-conditions list.
  • The third level of conditions works as OR sub-conditions list.
  • Nesting of conditions matches the rule OR (the first level of the arguments) -> AND -> OR -> AND -> ...
  • For a better understanding of how to build AND queries with objects please check the object helper documentation.

Structure

Copy
<!-- Filter on object keys -->
{{ filter (array (object key='value1') (object key='value2')) (object key='value1') }}
<!-- Filter on nested object keys -->
{{ filter (array (object key=(object prop='value1')) (object key=(object prop='value2'))) (object key=(object prop='value1')) }}
<!-- filter query base OR structure -->
{{ filter (array 1 2 3 ... ) c1 c2 c3 ... }}
result: c1 OR c2 OR c3

<!-- filter query base AND structure (the AND conditions described as sub-conditions) -->
{{ filter (array x y z) (array c1 c2 c3) }}
result: items that fit to c1 AND c2 AND c3

<!-- filter query a few OR from several AND conditions -->
{{ filter (array x y z) (array a1 a2 a3) (array b1 b2 b3) (array c1 c2 c3) }}
result: (a1 AND a2 AND a3) OR (b1 AND b2 AND b3) OR (c1 AND c2 AND c3)

<!-- filter with complex nested structure -->
{{ filter (array 1 2 3) (array a1 a2 (array x1 x2) ) (array b1 b2 b3) }}
results: items that fit to (a1 AND a2 AND (x1 OR x2) ) OR (b1 AND b2 AND b3)

Examples

Copy
<!-- Simple OR filter -->
{{filter (array 1 2 3) 1 3}}
result: 1,3

<!-- Simple OR filter -->
{{filter (array 'item1' 'item2' 'item3' 'item4' 'item3') 'item1' 'item2' 'item3'}}
result: item1,item2,item3,item3

<!-- Data bucket get all users with type='item1' -->
{{filter (dataRaw 'Users') (object type='item1')}}

<!-- Data bucket get all users with type='item1' OR type='item2' OR type='item3' -->
{{filter (dataRaw 'Users') (object type='item1') (object type='item2') (object type='item3')}}

<!-- Data bucket get all users with type='item1' AND category='some-category' -->
{{filter (dataRaw 'Users') (object type='item1' category='some-category')}}

<!-- Data bucket get all users with type='item1' OR category='some-category' -->
{{filter (dataRaw 'Users') (array (object type='item1') (object category='some-category'))}}

<!-- Mixed data filter -->
{{filter (array 'item1' 'item2' (object type='type1') (object type='type2')) 'item1' (object type='type2')}}

 object

Return an object that can be used in other helpers.

Examples

Copy
{{{object type='item1'}}}
result: {type: 'item1'}

{{{object type='item1' category='cat1'}}}
result: {type: 'item1', category: 'cat1'}

{{{object type=(array 1 2 3)}}}
result: {type: [1,2,3]}

{{{object type=(array 1 2 3)}}}
result: {type: [1,2,3]}

{{{object type=(filter (array 1 2 3) 1 3)}}}
result: {type: [1,3]}

 objectMerge

Merge two objects. The second object's properties will overwrite the first object's properties if they have the same key.

Examples

Copy
{{objectMerge (object key1='value1') (object key2='value2')}}
<!-- result: {key1: 'value1', key2: 'value2'} -->

<!-- Adding an id to the request's body -->
{{objectMerge (object id=uuid) (bodyRaw)}}

 sort

Return a sorted array of strings or numbers. To sort array of objects, use the sortBy helper.

Examples

Copy
{{sort (array 'item2' 'item1' 'item3') 'desc'}}
result: ['item3','item2','item1']

{{sort (array 'item2' 'item1' 'item3')}}
result: ['item1','item2','item3']

 sortBy

Return an array of objects sorted by a given key. This helper can be used with data buckets, use the dataRaw for that.

Examples

Copy
{{sortBy (array (object key1=10 key2=20) (object key1=30 key2=30) (object key1=15 key2=25)) 'key1'}}
result: [{"key2": 20, "key1": 10}, {"key2": 25, "key1": 15}, {"key2": 30, "key1": 30}]

{{sortBy (dataRaw 'Users') 'name' 'desc'}}

 reverse

Return an array with the elements in reverse order.

Examples

Copy
{{reverse (array 'item1' 'item2' 'item3')}}
result: ['item3','item2','item1']

 add

Add the numbers passed as parameters to each others. Unrecognized strings passed as arguments will be ignored.

Examples

Copy
{{add 1 1}}
result: '2'

{{add '1' '1'}}
result: '2'

{{add '1' 'foo' 1}}
result: '2'

 subtract

Subtract the numbers passed as parameters to the first parameter. Unrecognized strings passed as arguments will be ignored.

Examples

Copy
{{subtract 2 1}}
result: '1'

{{subtract '2' '1'}}
result: '1'

{{subtract '2' 'foo' 1}}
result: '1'

 multiply

Multiply the numbers passed as parameters to each others. Unrecognized strings passed as arguments will be ignored.

Examples

Copy
{{multiply 2 3}}
result: '6'

{{multiply '2' '3'}}
result: '6'

{{multiply '2' 'foo' 3}}
result: '6'

 divide

Divide the first parameter by the other numbers passed as parameters. Unrecognized strings passed as arguments will be ignored.

Examples

Copy
{{divide 4 2}}
result: '2'

{{divide '4' '2'}}
result: '2'

{{divide '4' 'foo' 2}}
result: '2'

 modulo

Compute the modulo of the first parameter by the second.

Examples

Copy
{{modulo 5 4}}
result: '1'

{{modulo '5' '4'}}
result: '1'

{{modulo '5' 'foo' 4}}
result: '1'

 ceil

Ceil the value of the number passed as parameter.

Examples

Copy
{{ceil 1.5}}
result: '2'

{{ceil '1.5'}}
result: '2'

 floor

Floor the value of the number passed as parameter.

Examples

Copy
{{floor 2.5}}
result: '2'

{{floor '2.5'}}
result: '2'

 eq

Verify if two numbers or strings are equal. Returns a boolean.
Returns false if type of the value not equals.

Examples

Copy
{{#if (eq 55 55)}}
  true
{{/if}}
Result: true

{{#if (eq 55 '55')}}
  true
{{else}}
  false
{{/if}}
Result: false

{{#if (eq 'x1' 'x1')}}
  true
{{/if}}
Result: true

 gt

Verify if the first number is greater than the second number. Returns a boolean.

Examples

Copy
{{#if (gt 56 55)}}
  true
{{/if}}
Result: true

 gte

Verify if the first number is greater than or equal to the second number. Returns a boolean.

Examples

Copy
{{#if (gte 55 55)}}
  true
{{/if}}
Result: true

 lt

Verify if the first number is lower than the second number. Returns a boolean.

Examples

Copy
{{#if (lt 55 56)}}
  true
{{/if}}
Result: true

 lte

Verify if the first number is lower than or equal to the second number. Returns a boolean.

Examples

Copy
{{#if (lte 55 55)}}
  true
{{/if}}
Result: true

 toFixed

Format a number using fixed-point notation.

Examples

Copy
{{toFixed 1.11111 2}}
Result: 1.11

 round

Return the value of a number rounded to the nearest integer.

Examples

Copy
{{round 0.499}}
Result: 0

 newline

Add a newline \n.

Examples

Copy
{{newline}}

 base64

Encode the parameter as base64. This can be used as an inline helper or block helper (see examples below).

Examples

Copy
{{base64 'test'}}

{{#base64}}
  firstname,lastname,countryCode
  {{#repeat 10}}
    {{faker 'person.firstName'}},{{faker 'person.lastName'}},{{faker 'address.countryCode'}}
  {{/repeat}}
{{/base64}}

 base64Decode

Decode a base64 string. This can be used as an inline helper or block helper (see examples below).

Examples

Copy
{{base64Decode 'YWJjZA=='}}

{{#base64Decode}}
  {{body 'base64content'}}
{{/base64Decode}}

 objectId

Create a valid ObjectId. It can generates the ObjectId based on the specified time (in seconds) or from a 12 byte string that will act as a seed. Syntax is based on bson-objectid package.

Examples

Copy
{{objectId 1414093117}}
{{objectId '54495ad94c934721ede76d90'}}

 includes

Search whether a string can be found in another string and returns the appropriate boolean.

Examples

Copy
{{includes 'Some data' 'data'}}

result: true

 substr

Return a portion of a string starting at the specified index and extending for a given number of characters afterwards.

Examples

Copy
{{substr 'Some data' 5 4}}

result: 'data'

 lowercase

Return the first string parameter lowercased.

Examples

Copy
{{lowercase 'ABCD'}}

result: 'abcd'

 uppercase

Return the first string parameter uppercased.

Examples

Copy
{{uppercase 'abcd'}}

result: 'ABCD'

 split

Split a string and return an array containing the multiples substrings. This helper can be used within handlebars' iterative helpers such as each. (Default separator is " ")

Examples

Copy
{{#each (split '1 2 3 4')}}
  item{{this}},
{{/each}}
result: item1,item2,item3,item4

{{#each (split 'This is my string.')}}
  {{this}},
{{/each}}
result: This,is,my,string,

 stringify

Return objects and arrays as a formatted JSON string indented with two spaces. This helper requires to be used with triple curly braces ({{{stringify ...}}}) to avoid escaping of the JSON string by Handlebars.

Examples

Considering an entering body:

Copy
{
  "prop1": "123",
  "prop2": {
    "data": "test"
  }
}

Copy
{{{stringify (bodyRaw 'prop2')}}}

Copy
{
  "data": "test"
}

 jsonParse

Parse a valid JSON string. The result can be used with other helpers like each, if, oneOf, lookup, etc.

Examples

Copy
{{#if (jsonParse 'true')}}
  value
{{/if}}

{{#if (eq (jsonParse '25') 25)}}
  value
{{/if}}

{{oneOf (jsonParse '[5, 56, 98]')}}
result: 5 or 56 or 98

{{lookup (jsonParse '{"data":"test"}') 'data'}}
result: test

<!-- Calling with a query string: ?json={"data":"test"} -->
{{lookup (jsonParse (queryParam 'json')) 'data'}}
result: test

 concat

Concatenate multiple primitive values into a single string, or multiple arrays into a single array. This helper can concatenate results from other helpers, or be used as a parameter of another helper (see examples below).

Examples

Copy
{{concat 'value1' 2 'value3'}}
{{concat @index (body 'id') 'value3'}}
{{#repeat (concat 1 2 3)}}...{{/repeat}}
{{concat (array 1 2) (bodyRaw 'list')}}
{{#each (concat (array 1 2) (array 3 4))}}...{{/each}}

 indexOf

Return the index of the searched 'data' inside the string. A last parameter (number) can be passed to start the search at a specific index.

Examples

Copy
{{indexOf 'Some data' 'data' 0}}

result: 5

 parseInt

Parse a number from a string.

 padStart

Pads a string with a given string (repeated, if needed) until the resulting string reaches the given length. The padding is applied from the start of the string.

Copy
{{padStart '5' 5 '0'}}

result: 00005

 padEnd

Pads a string with a given string (repeated, if needed) until the resulting string reaches the given length. The padding is applied from the end of the string.

Examples

Copy
{{padEnd '5' 5 '0'}}

result: 50000

 now

Display the current time in the chosen format. Format syntax is based on date-fns v3 format function and is optional (default to ISO string).

Examples

Copy
{{now 'YYYY-MM-DD'}}

 dateTimeShift

Shift a date by adding the number of years, months, etc. passed as parameters. The date and format parameters are optional. The helper will return the current date and time as an ISO string if omitted (yyyy-MM-ddTHH:mm:ss.SSSxxx). The formatting uses date-fns v3 format function.

Examples

Copy
{{dateTimeShift date='2021-01-01' format='yyyy-MM-dd HH:mm:ss' years=1 months=1 days=1 hours=1 minutes=1 seconds=1}}

 date

Return a random formatted date (using date-fns v3 format function) between a minimum and a maximum. Uses faker 'date.between' to generate the random date.

Examples

Copy
{{date '2020-11-20' '2020-11-25' "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"}}

 time

Return a random formatted time (using date-fns v3 format function) between a minimum and a maximum. Uses faker 'date.between' to generate the random time.

Examples

Copy
{{time '09:00' '10:00' 'HH:mm'}}

 dateFormat

Return a formatted date (using date-fns v3 format function).

Examples

Copy
{{dateFormat '2021-01-01' 'yyyy'}}
{{dateFormat (faker 'date.recent') 'yyyy'}}

 isValidDate

Validate a date using a combination of date-fns v3 toDate and isValid functions. Supports various syntaxes for the date parameter (string, number, Date object): "2024-01-01", "2021-01-01T00:00:00.000Z", 1727272454000, etc.

Examples

Copy
<!-- Valid -->
{{isValidDate '2022-01-01'}}
<!-- Valid -->
{{isValidDate '2022-01-01T00:00:00.000Z'}}
<!-- Invalid -->
{{isValidDate '2022-01-50'}}
<!-- Valid (unix time ms) -->
{{isValidDate 1727272454000}}
<!-- Validate a date coming from another helper -->
{{isValidDate (queryParam 'date')}}

 int

Return a random integer. Alias of faker 'number.int.

Examples

Copy
{{int 0 100}}

 float

Return a random float. Alias of faker 'number.float with precision = 10.

Examples

Copy
{{float 0 100}}

 boolean

Return a random boolean. Alias of faker 'datatype.boolean'.

Examples

Copy
{{boolean}}

 title

Return a random title. Alias of faker 'name.prefix'.

Examples:

Copy
{{title 'male'}}

 firstName

Return a random first name. Alias of faker 'person.firstName'.

Examples:

Copy
{{firstName}}

 lastName

Return a random last name. Alias of faker 'person.lastName'.

Examples:

Copy
{{lastName}}

 company

Return a random company name. Alias of faker 'company.companyName'.

Examples:

Copy
{{company}}

 domain

Return a random domain name. Alias of faker 'internet.domainName'.

Examples:

Copy
{{domain}}

 tld

Return a random top level domain. Alias of faker 'internet.domainSuffix'.

Examples:

Copy
{{tld}}

 email

Return a random email address. Alias of faker 'internet.email'.

Examples:

Copy
{{email}}

 street

Return a random address. Alias of faker 'location.streetAddress'.

Examples:

Copy
{{street}}

 city

Return a random city name. Alias of faker 'location.city'.

Examples:

Copy
{{city}}

 country

Return a random country name. Alias of faker 'location.country'.

Examples:

Copy
{{country}}

 countryCode

Return a random country code. Alias of faker 'location.countryCode'.

Examples:

Copy
{{countryCode}}

 zipcode

Return a random zip code. Alias of faker 'location.zipCode'.

Examples:

Copy
{{zipcode}}

 postcode

Return a random zip code. Alias of faker 'location.zipCode'.

Examples:

Copy
{{postcode}}

 lat

Return a random latitude. Alias of faker 'location.latitude'.

Examples:

Copy
{{lat}}

 long

Return a random longitude. Alias of faker 'location.longitude'.

Examples:

Copy
{{long}}

 phone

Return a random phone number. Alias of faker 'phone.number'.

Examples:

Copy
{{phone}}

 color

Return a random color. Alias of faker 'color.human'.

Examples:

Copy
{{color}}

 hexColor

Return a random hexadecimal color code.

Examples:

Copy
{{hexColor}}

 uuid/guid

Return a random UUID. Alias of faker 'string.uuid'.

Examples:

Copy
{{uuid}}
{{guid}}

 ipv4

Return a random IP v4. Alias of faker 'internet.ipv4'.

Examples:

Copy
{{ipv4}}

 ipv6

Return a random IP v6. Alias of faker 'internet.ipv6'.

Examples:

Copy
{{ipv6}}

 lorem

Return random lorem ipsum text. Alias of faker 'lorem.sentence'.

Examples:

Copy
{{lorem 50}}