Template

Definition

A template defines reusable logic that can be applied to multiple cases.

Templates are defined in YAML files with the spec field set to template. They can be stored in any location and organized as needed. Templates are resolved at parse time and merged into the execution graph, allowing them to be invoked from cases or other templates using the include action.

Template definition example

spec: template
title: Short human-readable template title
description: >
  Detailed human-readable description of the scenario template.
  May span multiple lines and is intended for documentation
  and reporting purposes
params:
- name: baseUrl
  type: string
  default: https://httpbin.org

Templates allow reuse of common workflows and logic across multiple cases, promoting modularity and maintainability in test design. By defining a template once and invoking it from multiple cases, you can avoid duplication and ensure consistency in your test scenarios.

Input schema

entity schemas.Template

Reusable template definition.

param description: str | None = None

Detailed human-readable description of the DSL element.

param envs: list[InputDefinition] = []

Definition of environment-based inputs required by the template.

Describes external configuration values, such as environment variables or secrets, that must be provided at execution time.

param params: list[InputDefinition] = []

Definition of parameters that must or may be provided when the template is invoked. Parameters define the input contract of the template and control its data-driven behavior.

param spec: Literal['template'] [Required]

param title: str | None = None

Short human-readable title of the DSL element.

param vars: dict[str, Deferred[Value]] = {}

Local context variables provided to block.

These variables are added to the execution context and can be referenced by subsequent steps.

Inclusion

A template can be invoked from a case or another template using the include action. The caller may pass variables into the action context via vars. These variables are treated as parameters of the invoked template.

The template execution context is isolated: only values explicitly declared as template parameters are transferred and shared. This allows templates to be reused in different contexts without unintended side effects, as they do not have access to the caller’s variables unless explicitly passed as parameters.

Template inclusion example

title: Example of invoking the template from a case
description: >
  This step demonstrates how a template can be invoked from
  within a case using the `include` action. The caller may pass
  variables into the action context via `vars`. These variables
  are treated as parameters of the invoked template. The template
  execution context is isolated: only values explicitly declared
  as template parameters are transferred and shared.
action: include
vars:
  argument: OK
file: echo.yaml
export:
  value: !var result.value
expect:
- title: Value exists in include result
  value: !var value
  match: OK

Input schema

action schemas.IncludeAction

DSL action for including and executing external template files.

param action: Literal['include'] = 'include'

param description: str | None = None

Detailed human-readable description of the DSL element.

param expect: list[Check] = []

List of checks that must pass after the action execution.

Each check validates some aspect of the action result or side effects. All expectations are evaluated to determine the success or failure of the step.

param export: dict[str, Deferred[Value]] = {}

Mapping of variable names to values derived from the action result.

Exported variables are merged into the execution context and become available to subsequent steps.

param file: Path [Required]

Path to a DSL template file to include.

The file must exist, be readable, and contain a valid DSL template definition. The template will be parsed and executed at runtime.

param output: str = 'result'

Name of the variable under which the action result context will be stored.

The stored value may later be referenced or selectively exported into the execution context.

param spec: Literal['step'] = 'step'

param title: str | None = None

Short human-readable title of the DSL element.

param vars: dict[str, Deferred[Value]] = {}

Local context variables provided to block.

These variables are added to the execution context and can be referenced by subsequent steps.