Choreo DSL Reference

choreo is an executable Domain-Specific Language (DSL) for writing “model clients” for your command-line applications and APIs. It uses a structured, human-readable format to define test scenarios that are easy to write, read, and maintain.

This document serves as the official reference guide for the .chor file format and its syntax.

File Structure: The BDD Hierarchy

A .chor file is structured hierarchically to tell a clear story, following the standard BDD pattern of Feature -> Scenario -> Test.

feature "A high-level description of the capability being tested"

# ... (settings, vars, actors)

scenario "A concrete example of the feature's behaviour" {

    test TestNameOne "The first step in the scenario" {  
        given:  
            # Pre-conditions and setup actions  
        when:  
            # The single action being tested  
        then:  
            # The expected outcomes and assertions  
    }

    test TestNameTwo "The second step, depending on the first" {  
        given:  
            Test has_succeeded TestNameOne  
        # ... and so on  
    }

    after {  
        # Cleanup actions that run after all tests in this scenario  
    }  
}

Keywords

choreo uses a set of keywords to define the structure and logic of a test suite.

feature

Provides a high-level description of the software capability being tested and groups related scenarios. A .chor file should contain exactly one feature.

Example:

feature "User account management via the CLI"

settings

A block for configuring the behavior of the choreo test runner for the current file.

Example:

settings {
  timeout_seconds = 10  
  stop_on_failure = true  
  expected_failures = 1
}

background

A block that provides a common set of given steps that will be executed before every scenario in the file. This is ideal for shared setup logic.

Example:

background {
  FileSystem create_dir "temp_data"
  FileSystem create_file "temp_data/initial.txt" with_content "setup data"
}

var

A keyword for defining key-value variables that can be used throughout the test file. This is useful for making tests more readable and maintainable by avoiding “magic strings.”

Example:

var FILENAME = "my_output.txt"  
var GREETING = "Hello, Choreo!"

Variables can also be defined as an array:

var PRODUCT = ["PROD-A", "PROD-B", "PROD-C"]

env

Declares a list of environment variables that the test suite requires. The test runner will read these from the shell environment where choreo is executed and make them available for substitution.

Example:

env {
    API_TOKEN
    GITHUB_USER
}

Or use a single environment variable like:

env HOME

actors

Declares the different systems or components that the test will interact with. The three currently supported actors are Terminal, System, FileSystem and Web. You must declare at least one actor per file.

Example:

actors {
    Terminal
    FileSystem
    Web
    System
}

Or use a singular actor like Web

actor Web

scenario

Describes a single, concrete example of the feature’s behaviour. It acts as a container for a sequence of related test blocks that form a user story or workflow.

Example:

scenario "A user can successfully create and then delete a file" {  
    # ... test blocks go here ...  
}

parallel scenario

To improve the performance of your test suites, especially those with many I/O-bound tests (like HTTP requests), you can run scenarios in parallel. By default, all scenarios run sequentially in the order they are defined. To mark a scenario for parallel execution, add the parallel keyword before the scenario keyword.

Example:

parallel scenario "This will run in parallel" {
    # ... tests ...
}

parallel scenario "This will also run in parallel" {
    # ... tests ...
}

scenario "This will run sequentially after all parallel ones finish" {
    # ... tests ...
}

Important Considerations:

• State Isolation: Each parallel scenario runs with its own isolated state, including separate backends (Terminal, Web, etc.). Variables defined in a var block or via env are copied to each scenario, but changes to variables within one parallel scenario will not affect others.
• Dependencies: Tests within a parallel scenario can still depend on each other (e.g., Test has_succeeded ...), but you cannot have dependencies between different parallel scenarios.
• Resource Contention: Be mindful of resource contention (CPU, network, file system) when running many scenarios in parallel.

test

The core unit of testing in choreo. Each test block has a unique name (for dependencies) and a human-readable description. It is composed of given, when, and then blocks.

Example:

test FileIsCreated "it creates a new file with content" {  
    given: # ...  
    when:  # ...  
    then:  # ...  
}

after

An optional block inside a scenario that contains a list of cleanup actions. These actions are executed after all test blocks within that scenario have completed, regardless of whether they passed or failed.

Example:

scenario "..." {  
    # ... tests ...

    after {  
        FileSystem delete_file "${FILENAME}"  

task

Defines a reusable, parameterised block of actions and/or conditions. Tasks act as “drivers” that encapsulate implementation details, allowing scenarios to remain focused on business intent. Tasks can be called from given, when, or then blocks.

Example:

# Define a task with parameters
task authenticate(token, endpoint) {
    Web set_header "Authorization" "Bearer ${token}"
    Web http_get "${endpoint}"
}

task verify_success() {
    Web response_status is_success
    Web response_time is_below 2s
}

# Call tasks in a test
scenario "API Health" {
    test HealthCheck "Service responds correctly" {
        given:
            Web set_header "User-Agent" "test-runner/1.0"
        when:
            authenticate("my-token", "/health")
        then:
            verify_success()
    }
}

Tasks support string, number, and duration arguments. For a complete guide on using tasks effectively, see Tasks and Drivers. }
}

## Test Blocks: Given, When, Then

Each `test` block is structured using the standard BDD keywords to create a clear narrative.

#### `given`:

The `given` block sets up the context for a test. It can contain a mix of **actions** (to set up the environment) and
**conditions** (to check pre-requisites, including dependencies on other tests).

**Example:**

```choreo
given:  
    # Action: Ensure a clean state  
    FileSystem delete_file "data.txt"  
    # Condition: This test can only run after the setup test has passed  
    test has_succeeded InitialSetup

when:

The when block contains the single, specific action that is being tested. A when block should contain only actions, not conditions.

Example:

when:  
    Terminal run "data-processor --input data.txt"

then:

The then block contains the assertions that verify the outcome of the when action. A then block should contain only conditions. The test passes if all then conditions are met.

Example:

then:  
    Terminal last_command succeeded  
    FileSystem file_exists "output.txt"

Data-Driven Testing with foreach

To test the same workflow with different sets of data without duplicating your test logic, choreo provides a powerful foreach construct.

The foreach block iterates over an array variable and dynamically generates a test block for each item in the array.

1. Defining Array Variables

Before you can use a foreach loop, you must define an array of strings in your var block using square bracket []syntax.

Example:

var PRODUCTS = ["PROD-A", "PROD-B", "PROD-C"]

2. The foreach Block

The foreach block must be placed inside a scenario. It defines a loop variable (e.g. ITEM) and the array variable to iterate over (e.g. ${PRODUCTS}). The parser then “unrolls” this loop, creating a separate test block for each item.

The loop variable can be used with ${...} syntax to dynamically generate test names, descriptions, and the content of the test steps themselves.

3. Complete Example

This example demonstrates how to use a foreach loop to test adding multiple products to a shopping cart. It generates three distinct test blocks from a single, clean definition.

feature "HTTP POST with foreach using httpbin"
actors: Web, System
var URL = "https://httpbin.io"
var PRODUCTS = ["PROD-A", "PROD-B", "PROD-C"]

scenario "Adding multiple items to the cart" {

    # 1. The foreach loop iterates over the PRODUCTS array.
    foreach ITEM in ${PRODUCTS} {

        # 2. A test block is defined inside. The loop variable `ITEM`
        #    is used to create a unique and descriptive test name.
        test "AddToCart_${ITEM}" "Add ${ITEM} to cart" {
            given:
                Test can_start
                System log "Adding item: ${ITEM}"
            when:
                Web set_header "Content-Type" "application/x-www-form-urlencoded"
                # 3. The loop variable is used in the request body.
                Web http_post "${URL}/post" with_body "product_id=${ITEM}"
            then:
                Web response_status_is 200
                # 4. The loop variable is used in the assertion.
                Web response_body_contains "product_id=${ITEM}"
        }
    }
}

Vocabulary: Actions & Conditions

This is the reference for all available commands that can be used within the test blocks.

Wait Conditions

State Conditions

Terminal Commands

Actions

Conditions

System Commands

Actions

Conditions

Note: All System conditions are cross-platform and work on Windows, macOS, and Linux.

FileSystem Commands

Actions

Conditions

Web Commands

Actions

Conditions

Variables

choreo supports both environment variables and file-defined variables for making tests dynamic. File-defined variables can be string, number, list of strings or an list of objects.

var TEST1 = 0
var TEST2 = "test"
var TEST_LIST = ["TEST1", "TEST2", "TEST3"]
var TEST_ARRAY = [
    { NAME: "test1", VALUE: "test", NOTE: "First test" },
    { NAME: "test2", VALUE: "test", NOTE: "Second test" }
]

Substitution

To use a variable, use the ${VAR_NAME} syntax inside any string literal. The test runner will replace this placeholder with the variable’s value before executing the step.

Example:

var FILENAME = "output.log"  
when:  
  Terminal run "echo 'hello' > ${FILENAME}"  

choreo also supports list indexing for variables:

var PRODUCT = ["PROD-A", "PROD-B", "PROD-C"]
given:
    System log "${PRODUCT[2]}" # PROD-C