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

Test plans store shared template defaults and per-test variants. Each variant runs its test once with its own values. Set these in the Test Plan editor.

When starting a plan via the API, set render_templates: true and supply template_data to override saved defaults for that execution:

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

Values take priority in this order: variant → launch override → plan default. The example supplies environment and locale to runs that leave those values unset in their variants.

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").