Skip to main content

Block Helpers In Template Engine

Beeceptor's template engine supports a range of block operators for flow control and customizing mock responses. Explore examples of if/else, switch, and repeat/for-loop constructs to see how you can tailor responses to your needs.

Note: Within a mock rule, the template engine is off by default. You need to explicitly mark a rule to enable usage Handlebars templates before start using block constructs.

Switch​

The switch block allows you to create conditional responses by matching on specific input values, like query parameters, or an attribute from request body.

Syntax​

{{#switch expression}}
  {{#case 'value1'}}content-1{{/case}}
  {{#case 'value2'}}content-2{{/case}}
  {{#default}}default-content{{/default}}
{{/switch}}

Let’s break down each component:

  • #switch: This starts the switch block. The expression can be a static value or an expression to be evaluated. Its value determines which #case block will be executed.
  • #case 'valueX': Each #case block checks if the expression matches valueX. If it does, the content within this block (e.g., content-1 or content-2) is rendered in the response.
  • #default: This is an optional block that provides a fallback option. If the expression does not match any of the specified cases, the content inside the #default block is rendered.

Video Demo​

Examples​

The following template returns different name based on given id in the query parameter. The switch statement handles two cases and a default value.

Template used:

{
  "name": 
{{#switch (queryParam 'id')}}
{{#case '1'}}"Alex"{{/case}}
{{#case '2'}}"Jenny"{{/case}}
{{#default}}"Some-Name"{{/default}}
{{/switch}},
  "status": "The switch/case are amazing!" 
}

Request triggered:

GET /find-all-users?id=1

Response generated: The name as Alex is picked because from the block {{#case '1'}}"Alex"{{/case}}.

{
  "name": "Alex",
  "status": "The switch/case are amazing!"
}

If & Else​

The if helper in Beeceptor allows you to conditionally emit content in HTTP responses. When you use this helper, Beeceptor evaluates its argument. If the result is false, undefined, null, an empty string (""), zero (0), or an empty array ([]), the block of content associated with this if helper will not be displayed.

Syntax​

{{#if expression}}
content
{{/if}}

Here, the content is the text block will be returned in the HTTP response only when the expression is satisfied. The result of the expression should be non-empty and non-zero to be satisfied. Refer to the examples on how to build expression logic.

You can build complex checks for expression. For instance,

  • to check the presence of a field in a POST request's body, use an expression like (body 'status'). This parses the request body as JSON and evaluates the status field's value.
  • to check the value of a field in the POST request's body, use a sub-expression (eq 'paid' (body 'status')).

Refer to a full list of supported operators, syntax and example here.

Examples​

In the following example, the template checks the order status, and returns additional fields in JSON. You can see a conditional field amountToCollect. When the order status is paid, amountToCollect is set to 0, else it is equal to the order amount.

Template used:

{
    "customerId": "{{body 'customerId'}}",
    "productId": "{{body 'productId'}}",
    "quantity": {{body 'quantity' '1'}},
    "status": "{{body 'status'}}",
    "amount": {{body 'amount'}},
{{#if (eq 'paid' (body 'status'))}}
    "amountToCollect": 0,
{{else}}
    "amountToCollect": {{body 'amount'}},
{{/if}}
}

Payload for the POST request:

{
    "customerId": "1234",
    "productId": "PRODUCTID",
    "quantity": 3,
    "status": "paid",
    "amount": 30
}

Response generated:

{
    "customerId": "1234",
    "productId": "PRODUCTID",
    "quantity": 3,
    "status": "pending",
    "amount": 30,
    "amountToCollect": 0,
}

When the status field in the request body has value paid, the template engine emits "amountToCollect" : 0. Else, the value specified in the amount field is replicated for amountToCollect.

Technical Details​

Here's a detailed technical breakdown of how the If block functions:

  1. Checkout the list of supported operators on this page. Please reach out to Support Team for additional operators support.
  2. The If clause lets you extract values from query parameters, path, headers, or the request body. Use the expression clause as shown in the above examples.

Repeat​

Beeceptor adds an advanced feature known as the Repeat block in the template engine. This allows you to simulate loop constructs while generating mock data. This feature is particularly beneficial when creating a response with JSON arrays, GET API call to retrieve objects or search results in an API response.

Syntax​

{{#repeat count}}
content
{{/repeat}}

Here, the content is the text block to be repeated for the given count times. The argument count has to be a number. A comma will be added between consecutive content blocks.

Examples​

Generating a JSON array of three users objects.

Template used:

[
{{#repeat 3}}
  { 
    "name": "Dave",
    "address": "45 Brookfield",
    "country": "US"
  },
{{/repeat}}
]

Response generated:

[
  { 
    "name": "Dave",
    "address": "45 Brookfield",
    "country": "US"
  },
  { 
    "name": "Dave",
    "address": "45 Brookfield",
    "country": "US"
  },
  { 
    "name": "Dave",
    "address": "45 Brookfield",
    "country": "US"
  }
]

Technical Details​

Here's a detailed technical breakdown of how the Repeat Block functions:

  1. Fixed Iteration Count: By giving a single numerical value as an argument, the repeat block will execute a predetermined number of iterations. This results in consistent output for each request, with the contents of the repeat block duplicated exactly per the specified iteration count.
  2. Random Iteration Range: If you give two numerical values as arguments, it activates a random iteration mode. The system will randomly select a number within this range, leading to a variable number of iterations. Thus, each request generates a unique output as the repeat block's content is replicated a random number of times.
  3. Intelligent Comma Insertion: The repeat block is designed to automatically insert commas (,) between consecutive blocks to ensure the generation of a syntactically correct JSON array or a item list of items. In addtion, it smartly omits the comma after the last block to maintain JSON validity. You can override this behavior by adding comma=false in the repeat argument, which disables the automatic comma insertion. Refer to an example in the table above.
  4. Iteration Cap: The repeat block enforces a maximum limit of 1,000 iterations. If you specify a value exceeding this limit, it is automatically adjusted down to 1,000. This cap ensures efficient performance and avoids excessively large data outputs.
  5. Contextual Keywords: The block supports dynamic keywords such as @index and @total, providing you with contextual information about the current iteration's index and the total iteration count, respectively. This feature is especially useful for labeling or indexing elements within the JSON array output, like assigning unique id fields.

Video Demo​