testscript-rs/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

testscript-rs is a Rust crate for testing CLI tools using filesystem-based script files in the .txtar format. It mirrors the functionality of Go's github.com/rogpeppe/go-internal/testscript package.

Development Commands

# Run all tests
cargo test

# Run specific test suite
cargo test --test integration
cargo test --test builtin_commands
cargo test parser::tests::

# Run single test
cargo test test_basic_api

# Format code (always run before committing)
cargo fmt

# Check code formatting
cargo fmt --check

# Check code quality
cargo clippy --all-targets -- -D warnings
cargo check

# Build and run examples
cargo run --example test_runner

# Test the sample CLI example
cd examples/sample-cli && cargo test

Architecture

The crate is organized into three main modules that work together:

Core Modules

parser.rs - Parses .txtar format files into structured representations:

• Script struct contains commands and files from a test script
• Command struct represents individual command lines with args, conditions, negation
• TxtarFile represents file blocks embedded in the script
• Handles quoted arguments, escape sequences, conditions ([unix]), negation (!), and background processes (&)

run.rs - Execution environment and command dispatch:

• TestEnvironment manages isolated temporary directories for each test
• RunParams configures the test runner (internal, used by Builder)
• Built-in command implementations (exec, cmp, stdout, stderr, exists, mkdir, cp, mv, rm, chmod, env, cmpenv, stdin, etc.)
• Custom command dispatch system
• Background process management

error.rs - Error types using thiserror for structured error handling

Public API

The main public API is the testscript module with a builder pattern:

testscript::run("testdata")
    .setup(|env| { /* compile CLI tool */ })
    .command("custom", |env, args| { /* custom logic */ })
    .condition("feature", true)
    .execute()

Key Implementation Details

Script Parsing: The parser handles complex .txtar format with file blocks, command parsing with proper quoting, and conditional execution markers.

Test Isolation: Each test script runs in a completely isolated temporary directory with its own environment variables and file system.

Command System: Built-in commands are implemented as methods on TestEnvironment. Custom commands are function pointers stored in a HashMap and checked before built-ins during dispatch.

Background Processes: Commands ending with & spawn processes stored in a HashMap by name, managed with wait and kill commands.

Environment Variables: Full support including $WORK (working directory), custom variables, and substitution in file comparisons (cmpenv) and output patterns.

Test Structure

• tests/integration.rs - Main API tests including custom command usage
• tests/builtin_commands.rs - Tests for all built-in commands
• tests/edge_cases.rs - Parser edge cases and error conditions
• tests/integration_tests.rs - Original integration tests
• tests/setup_hook.rs - Setup functionality tests
• testdata/ - Go testscript compatibility test files (40 files from upstream)

Built-in Commands

Core: exec, cmp, stdout, stderr, cd, wait, exists, mkdir, cp, mv, rm, chmod, env, cmpenv, stdin, skip, stop, kill, unquote, grep, symlink

The command dispatch checks custom commands first, then falls back to built-ins, enabling easy extension.