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 readable given steps that apply to all scenarios in a feature.

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!"

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, FileSystem and Web. You must declare at least one actor per file.

Example:

actors {
    Terminal
    FileSystem
    Web
}

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 ...  
}

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}"  
    }  
}

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:

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 runs "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"

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

FileSystem Commands

Actions

Conditions

Web Commands

Actions

Conditions

Variables

choreo supports both environment variables and file-defined variables for making tests dynamic.

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 runs "echo 'hello' > ${FILENAME}"