Core Concepts

The choreo DSL is designed to be readable and structured. Every test file follows a consistent hierarchy of concepts that describe a feature, its actors, and specific test scenarios. This page breaks down those fundamental building blocks.

The Anatomy of a .chor File

Think of a .chor file as a script for a play. It has a main theme (feature) and a cast of characters (actors). The play is broken into scenes (scenarios), and each scene contains one or more specific sequences of action (tests). Finally, the given, when, then steps act as the stage directions and dialogue that describe the plot of each test.

feature "User Authentication"
actor Terminal

scenario "Successful login attempt" {
    test VerifySuccessfulLogin "Verify login grants access" {
        given:
            # Assume a 'login' command exists
            Terminal run "login --user admin --pass secret123"
        when:
            # Check the output for a success message
            Terminal output_contains "Welcome, admin!"
        then:
            # The command should exit cleanly (0)
            Terminal last_command succeeded
    }
}

1. Features: The “What”

Every .chor file starts by declaring a feature. A feature is a high-level description of a single piece of your application’s functionality, like “User Authentication” or “File Uploads.” It acts as a container for all related test scenarios.

feature "A short, descriptive name for the functionality"

2. Actors: The “Who”

actors are the components or systems that will perform actions in your tests. Choreo has four built-in actors that act as specialised backends:

• Web: For making HTTP requests and testing APIs.
• Terminal: For running shell commands and inspecting their output.
• FileSystem: For creating, reading, and verifying files and directories.
• System: For debugging, controlling test flow, and managing the test environment.

You must declare which actors your feature will use at the top of the file.

actors {
    Terminal
    FileSystem
}

3. Scenarios & Tests: The “How”

A scenario is a single, concrete example of a feature’s behaviour. A feature can have multiple scenarios. For example, a “User Authentication” feature might have scenarios for both a successful login and a failed login.

Inside a scenario, you define one or more test blocks. Each test block is an individual, runnable test case with a clear success condition.

scenario "Handling invalid credentials" {
  test VerifyDeny "Verify login is denied" {
    ...
  }
}

4. Steps: The Action (Given, When, Then)

Each test is made up of steps that follow the popular Given-When-Then BDD structure. This format helps describe the context, the action, and the expected outcome in a clear, logical flow.

• given: Sets up the initial state or preconditions. (“Given I have a user in the database…”)
• when: Describes the key action that is being tested. (“When I send a POST request to the login endpoint…”)
• then: Contains the assertions that verify the outcome. (“Then the API should respond with a 200 OK status…”)

How choreo Works

When you run a Choreo test, an internal parser reads your human-readable .chor file and translates each step into a command. These commands are then executed by the declared actors, which act as the bridge between your test and the system. For a deeper look at the parser and backend implementations, see our Architecture documentation.

Summary

By structuring your .chor files with feature, actors, scenario, and test blocks, you create clear, readable, and maintainable tests that describe both the behavior of your application and the intent behind each test case. This organisation helps you and your team understand what is being tested and why, making it easier to maintain and extend your test suite over time.