choreo 0.10.1

About

choreo is an executable Domain-Specific Language (DSL) for writing automated, behaviour-driven tests for command-line applications and system interactions. It uses a structured, human-readable format inspired by Gherkin to define test scenarios that are easy to write, read, and maintain.

The goal of choreo is to provide the power and expressiveness of a BDD framework like Cucumber, but in a self-contained, executable format specifically designed for testing the shell.

Key Features

• Human-Readable BDD Syntax: Uses a given-when-then structure within test blocks to create clear, self-documenting tests.
• Executable Scripts: .chor files are complete, runnable tests. No separate "step definition" or "glue code" files are required.
• Stateful Scenarios: Capture variables from command output and reuse them in subsequent steps to test complex workflows.
• Multi-Actor System: Interact with and assert against multiple parts of your system in a single test.
  • Terminal: Control an interactive pseudo-terminal, check stdout, stderr, and command exit codes.
  • FileSystem: Create, delete, and verify files and directories as part of your test setup and assertions.
• Configurable Test Runner: Control test behavior with a settings block for features like timeouts and custom shell paths.
• CI-Friendly Reporting: Generates standard JSON reports for easy integration with CI/CD pipelines.

Example Usage

See web_health_check.chor for the above example in text format. There are many more examples in the examples directory.

Full Documentation

For a complete guide to all keywords, actions, conditions, and features, please see the official Choreo DSL Reference.

Getting Started

Prerequisites

You need Rust and Cargo installed.

Installing from crates.io

The easiest way to install choreo is to download it from crates.io. You can do it using the following command:

cargo install choreo

If you want to update choreo to the latest version, execute the following command:

choreo update

Building from source

Alternatively you can build medi from source using Cargo:

git clone https://github.com/cladam/choreo.git
cd choreo
cargo build --release

# The binary will be located at target/release/choreo
# Optionally, you can add it to your PATH
export PATH=$PATH:$(pwd)/target/release

# Or, install it system-wide
cargo install --path .

Command-Line Usage

Create a new test file

Use the init command to generate a new example .chor file. This is a great starting point for a new test suite.

# Create a new test file with default name "test.chor"
choreo init

# Create a new test file
choreo init --file "my_test.chor"

Validate a test file

Use the validate command to check the syntax and structure of a .chor file without executing it.

# Validate the default test.chor file
choreo validate

# Validate a specific file
choreo validate --file "examples/advanced_matchers.chor"

Lint a test file

Use the lint command to both check syntax and semantics of a .chor file without executing it.

# Validate and run linting on the default test.chor file
choreo lint

# Lint a specific file
choreo lint --file "examples/advanced_matchers.chor"

Run a script

Use the run command to execute a .chor file. Use the --verbose flag for detailed debug output.

# Run a test script
choreo run --file "examples/redirecting_output_tee.chor"

# Run with verbose logging
choreo run --file "examples/redirecting_output_tee.chor" --verbose

Parse a JSON report

Use the helper script to summarize a report or show failing steps. Requires only Python 3 (no external dependencies).

# Parse the latest report in ./reports
python3 scripts/parse_test_report.py

# Parse a specific report
python3 scripts/parse_test_report.py reports/choreo_test_report_20260227_202231.json

# Output as structured JSON (for CI pipelines)
python3 scripts/parse_test_report.py --json reports/choreo_test_report_20260227_202231.json

Status & Roadmap

choreo is currently in the beta stage. The core engine is functional, but more to add before production-ready.

The journey ahead includes:

• A dedicated editor with syntax highlighting and linting.

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.