Relux — Rust Integration Test Framework

What is this?

Relux is a Rust reimplementation of hawk/lux (LUcid eXpect scripting) — an Expect-style test automation framework. It controls interactive shell programs by sending input and matching output against expected patterns (regex or literal). The goal is a fast, standalone binary with no Erlang dependency.

Project Status

Working prototype — tests can be authored and executed end-to-end.

Relux DSL (.relux files)

See Semantics and Syntax

A hands-on guide to writing integration tests with Relux, from first test to full test suite.

0. Introduction — what Relux is, the problem it solves, and the core mental model of Expect-style testing
1. Installation — building Relux from source
2. Getting Started — scaffolding a project, configuring the shell, and running the first test
3. Send, Match, and Logs — the fundamental operators for sending input, matching output, and debugging failures
4. The Output Buffer — how shell output accumulates and the cursor model behind matching
5. Built-in Functions — the echo problem, match_prompt(), and the full built-in function toolkit
6. Variables — declaring variables, string interpolation, reassignment, and scoping
7. Regex Matching — matching output with regex patterns and extracting capture groups
8. Functions — defining reusable test logic with parameters and arity-based dispatch
9. Timeouts — controlling timing at every level with tolerance and assertion timeouts
10. Fail Patterns — continuous error monitoring that catches problems anywhere in the test
11. Effects and Dependencies — reusable test infrastructure with dependency graphs and overlay variables
12. Pure Functions — functions that compute values without touching a shell
13. Cleanup — teardown blocks for removing files, collecting artifacts, and undoing side effects
14. Modules and Imports — organizing a multi-file test suite with shared effects and functions
15. Condition Markers — conditionally skipping or running tests based on environment
16. The CLI — complete coverage of relux new, check, run, and history

A1. Best Practices — all best-practices guidelines from the series in one place

Planned Features

• Per-shell command override: per-shell executable override via shell block attributes (global shell command now configurable in Relux.toml)
• Custom scaffold templates: user-defined templates for relux new --test and relux new --effect via Relux.toml, replacing the built-in defaults
• Make sleep, log, and annotate impure BIFs: these have observable side effects (time delay, output) and don't belong in pure context — move them from lookup_pure to lookup so they require a shell context

Planned RFCs

• Interactive debugger: step through test scripts interactively with breakpoints
• Multiple marker semantics: define AND/OR combination semantics when multiple condition markers are stacked on a single test or effect

Known Bugs

• Cleanup ordering: all test and effect shells should be terminated before any cleanup block runs. Currently cleanup runs interleaved with shell termination. The correct order is: terminate all test shells, terminate all effect shells, then run cleanup blocks (test cleanup first, then effect cleanup in reverse topological order).
• Cleanup variable scope: test-level and effect-level let variables should be available in their respective cleanup blocks. Currently cleanup blocks get a fresh empty scope and can only see overlay variables (for effects) and environment variables.

Tech Stack

• Language: Rust (edition 2024)
• Lexer: logos (~0.16)
• Parser: chumsky (~0.12)

Architecture

1. Lexer (logos): tokenizes .relux files
2. Parser (chumsky): tokens → AST
3. Resolver: AST → IR, module imports, effect dependency graph
4. Runtime: walks IR, spawns PTY shells via tokio, executes send/match with timeouts
5. Reporter: test results with ariadne-powered diagnostic output

Conventions

• File extension: .relux
• Examples go in examples/
• Follow Rust 2024 edition idioms