Templating with Handlebars

Use Handlebars templates to make test cases reusable by passing dynamic values at runtime. This is useful when you want to run the same test with different inputs—different servers, user credentials, locales, or any other variable data.

Quick Start

1. Add Template Variables to Your Test Case

In your test step instructions, use {{variable_name}} syntax:

Select {{server_name}} from the server dropdown

or

Log in with the following credentials: {{username}} / {{password}}

2. Pass Values via the API

When starting a run via the Start a Run API, set render_templates: true and provide your values in template_data:

{
  "multiplayer_test_id": "abc123...",
  "deployment_config_id": "def456...",
  "render_templates": true,
  "template_data": {
    "server_name": "us-west-2"
  }
}

The agent will see the rendered instruction: “Select us-west-2 from the server dropdown”

Common Use Cases

Running Tests Against Different Environments

Run the same test suite against multiple servers or regions without creating separate test cases:

Test step:

Connect to the {{region}} server from the server selection menu

API calls:

// Run 1: US region
{
  "multiplayer_test_id": "...",
  "deployment_config_id": "...",
  "render_templates": true,
  "template_data": { "region": "US-East" },
  "additional_tags": ["region:us-east"]
}
 
// Run 2: EU region
{
  "multiplayer_test_id": "...",
  "deployment_config_id": "...",
  "render_templates": true,
  "template_data": { "region": "EU-West" },
  "additional_tags": ["region:eu-west"]
}

Dynamic Test Data

Pass variable data for each test run (items, characters, settings):

Test step:

Purchase {{item_name}} from the in-game shop and verify it appears in inventory

API call:

{
  "multiplayer_test_id": "...",
  "deployment_config_id": "...",
  "render_templates": true,
  "template_data": {
    "item_name": "Golden Sword"
  },
  "additional_tags": ["item:golden-sword"]
}

Parameterized Bug Verification

Verify specific bugs by passing their details to a generic verification test:

Test step:

Attempt to reproduce the following issue:

{{issue_description}}

Report whether the issue was reproduced and mark the result accordingly.

API call:

{
  "multiplayer_test_id": "...",
  "deployment_config_id": "...",
  "render_templates": true,
  "template_data": {
    "issue_description": "Clicking Submit with an empty form shows a blank page instead of validation errors"
  },
  "additional_tags": ["ticket:PROJ-1234"]
}

Test Plans with Templates

Templating works with test plans too. All tests in the plan receive the same template data:

{
  "test_plan_id": "...",
  "deployment_config_id": "...",
  "render_templates": true,
  "template_data": {
    "environment": "staging",
    "locale": "de-DE"
  }
}

Tips

• Use tags for filtering: Add additional_tags with your template values (e.g., ["region:us-east"]) to easily filter and find runs later
• Multiple variables: You can use as many template variables as needed in a single test case
• Nested values: Access nested data with dot notation: {{user.email}}

Handlebars Syntax

Nexus uses Handlebars  as its templating engine. Here’s a quick reference.

Basic Expressions

Use double curly braces {{}} for variables:

Hello {{name}}!

With the data { "name": "World" }, this renders as: Hello World!

Conditionals

{{#if premium_user}}
  Navigate to the premium dashboard
{{else}}
  Navigate to the free tier dashboard
{{/if}}

Loops

Test the following items:
{{#each items}}
  - {{this}}
{{/each}}

For complete documentation, visit the official Handlebars documentation .

Custom Helpers

Nexus provides several custom Handlebars helpers:

isNotEmpty

Checks if a value is not empty. For objects, returns true if the object has at least one key.

{{#if (isNotEmpty user.settings)}}
  User has settings configured
{{/if}}

upper

Converts a string to uppercase.

{{upper name}}

lower

Converts a string to lowercase.

{{lower title}}

slice

Extracts a section of a string or array. Works like JavaScript’s slice().

Parameters:

• list - The string or array to slice
• start - Zero-based index at which to begin extraction (negative counts from end)
• end - (Optional) Zero-based index before which to end extraction

{{#each (slice items 0 3)}}
  {{this}}
{{/each}}

Examples:

• slice([1, 2, 3, 4, 5], 0, 3) → [1, 2, 3]
• slice([1, 2, 3, 4, 5], 2) → [3, 4, 5]
• slice("Hello World", 0, 5) → "Hello"
• slice([1, 2, 3, 4], -2) → [3, 4]

Combining Helpers

{{upper (slice name 0 1)}}{{lower (slice name 1)}}

This capitalizes the first letter (e.g., "john" → "John").