Advanced Topics

While the core of choreo is writing tests, the ecosystem includes powerful tools to help you maintain quality, work with variables, and integrate choreo into your workflow. This section covers those advanced features.

Validating and Linting Tests

choreo comes with a built-in validate command that acts as a comprehensive linter for your .chor files. It’s a great tool for catching errors, potential issues, and following best practices before you run your tests, especially in an automated CI pipeline.

The validator performs three levels of checks:

Error Checks (E codes)

Critical issues that must be fixed:

Warning Checks (W codes)

Potential issues that should be reviewed:

Info Checks (I codes)

Informational suggestions:

You can run the linter from your terminal like this:

# Validate a test chor file
choreo lint /path/to/your/test.chor

The linter will output detailed diagnostic messages with specific line numbers, error codes, and suggestions to help you fix issues and improve your test quality. It also tracks variable usage to ensure all defined variables are actually used in your tests.

Working with Variables and Environment Secrets

Variables in choreo allow you to store and reuse values throughout your tests. This is particularly useful for sensitive information like API keys or tokens, which you don’t want to hardcode in your test files.

Local Variables

You can define local variables within your .chor file using the var keyword. These variables can then be referenced using ${VARIABLE_NAME} syntax.

feature "Fetch a user profile"
actor Web

var BASE_URL = "https://api.staging.myapp.com"
var USER_ID = "user-123"

scenario "User Profile Tests" {
    test FetchProfile "Fetch user profile" {
        given:
            Test can_start
        when:
            Web http_get "${BASE_URL}/users/${USER_ID}"
        then:
            Web response_status is_success
            Web json_path at "/myapp/user" equals "${USER_ID}"
    }
}

List and array variables

choreo support creating lists and arrays as variables that will be substituted, this can be used in the foreach loop which makes choreo very powerful and it enables data-driven testing.

feature "Fetch users profile"
actor Web

var BASE_URL = "https://api.staging.myapp.com"
var USERS = ["user-123", "user-321", "user-213"]

scenario "User Profile Tests" {
    foreach USER in ${USERS} {
        test "FetchProfile_${USER}" "Fetch user profile for user ${USER}" {
            given:
                Test can_start
            when:
                Web http_get "${BASE_URL}/users/${USER}"
                System log "Fetching ${USER}'s profile"
            then:
                Web response_status is_success
                Web json_path at "/myapp/user" equals "${USER}"
        }
    }
}

Environment Variables for Secrets

For sensitive data like API keys or passwords, it’s best practice to pass them in from the environment. choreo automatically makes environment variables available for substitution.

# In your terminal
export AUTH_TOKEN="super-secret-token"
choreo run /path/to/test.chor

In your .chor file, you can reference this environment variable like so:

feature "Fetch a user profile"
actor Web

env AUTH_TOKEN
var BASE_URL = "https://api.staging.myapp.com"
var USER_ID = "user-123"

scenario "User Profile Tests" {
    test FetchProfile "Fetch user profile" {
        given:
            Test can_start
        when:
            Web set_header "Authorization" "Bearer ${AUTH_TOKEN}"
            Web http_get "${BASE_URL}/users/${USER_ID}"
        then:
            Web response_status is_success
            Web json_path at "/myapp/user" equals "${USER_ID}"
    }
}

Editor Integration (Upcoming)

We are actively developing features to improve the choreo authoring experience directly in your favorite code editor.

This will bring a much richer and more productive editing experience to choreo. Stay tuned for updates!