Case¶

Definition¶

A case represents a runnable test scenario. It is defined in a YAML document with the spec field set to case. After the case, you can define any number of nested steps, which are executed sequentially. Cases can also include metadata and variables that are accessible within the execution context.

Case definition example¶

spec: case
title: Short human-readable case title
description: >
  Detailed human-readable description of the scenario.
  May span multiple lines and is intended for documentation
  and reporting purposes
metadata:
  tags:
  - engine
  - example
vars:
  baseUrl: https://httpbin.org

Only documents under a case are executed.

Input schema

entity schemas.Case¶

Executable test case 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 metadata: dict[str, Value] = {}¶: Additional metadata associated with the test case.

param params: list[Parameter] = []¶

Definition of parameters used to drive data-driven execution of the test case.

Parameters define the input space and control combinatorial execution of the case.

param spec: Literal['case'] [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.

Environment¶

You can use the envs field to define environment variables that will be set during the execution of the case. These variables are accessible to all steps within the case and can be used to configure the execution environment.

Environment variables example¶

---
spec: case
title: Case with environment variables
vars:
  baseUrl: https://httpbin.org
envs:
- name: API_KEY
  description: API key for authentication
  required: yes
  secret: yes

---
title: Example of accessing environment variable in a step
action: http.get
url: !var baseUrl
headers:
  x-api-token: !secret envs.API_KEY

Input schema

entity schemas.InputDefinition¶

Definition of a single input parameter.

param default: Value = None¶

Default value of the input parameter.

Used when the input is not explicitly provided. Must not be specified for required inputs.

param description: str | None = None¶: Human-readable description of the input parameter.

param name: str [Required]¶

Unique identifier of the input parameter.

Used to reference the input value in expressions, templates, and variable lookups. Must start with a letter and contain only letters, digits, and underscores.

param required: bool = False¶

Indicates whether the input parameter must be explicitly provided by the user or calling scenario.

Required inputs must not define a default value.

param secret: bool = False¶

Marks the input parameter as sensitive.

Secret inputs are masked in logs, reports, and error messages.

param type: TypeName = 'str'¶: Data type of the input parameter.

Only simple types are supported as environment variable values:

type schemas.TypeName = Literal['str', 'int', 'float', 'bool', 'object', 'list']¶

Parametrize¶

Case can be parameterized using the params field. This allows you to define variables that can be used within the case and its steps, enabling dynamic and flexible test scenarios.

On definition of several values for a parameter, the case will be executed once for each value, allowing you to easily test different scenarios without duplicating the case definition. On definition of several parameters with several values, the case will be executed for each combination of parameter values.

Case parameterization example¶

---
spec: case
title: Parameterized case example
params:
- title: The API url to use for the request
  name: apiUrl
  values:
  - https://httpbin.org/ip
  - https://httpbin.org/user-agent
  - https://httpbin.org/headers

---
title: Example of accessing case parameter in a step
action: http.get
url: !var params.apiUrl

Input schema

entity schemas.Parameter¶

Parameter definition for data-driven execution.

param description: str | None = None¶: Detailed human-readable description of the DSL element.

param name: str [Required]¶

Identifier of the parameter.

The name is used to reference the parameter value in expressions, templates, and step definitions.

param title: str | None = None¶: Short human-readable title of the DSL element.

param values: list[Value] = []¶: List of possible values for the parameter.