From 55aad7e48ce28edbbaf4ac484d4ae9590465bee9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 27 Sep 2025 04:56:26 +0000 Subject: [PATCH] Update README and function docs to reflect current API implementation Co-authored-by: imjasonh <210737+imjasonh@users.noreply.github.com> --- README.md | 24 ++++++++++-------- src/lib.rs | 74 ++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 69 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 38221cd..08b0a67 100644 --- a/README.md +++ b/README.md @@ -114,24 +114,28 @@ custom-cmd arg1 arg2 arg3 ### With Advanced Conditions -testscript-rs supports network detection, environment variable conditions, and automatic program detection: +testscript-rs automatically detects network, common programs, and supports environment variable conditions: ```rust +// Everything detected automatically - network, 35+ common programs testscript::run("testdata") - .auto_detect_network() - .auto_detect_programs(&["docker", "git", "npm"]) - .condition("env:CI", std::env::var("CI").is_ok()) + .execute() + .unwrap(); + +// Manual conditions still supported for custom scenarios +testscript::run("testdata") + .condition("custom", my_custom_check()) .execute() .unwrap(); ``` -#### Condition Types +#### Built-in Condition Types -- **Platform conditions**: `[unix]`, `[windows]`, `[linux]`, `[darwin]` -- **Network conditions**: `[net]` - Auto-detected or manually set -- **Program conditions**: `[exec:program]` - Check if program exists in PATH -- **Environment variables**: `[env:VAR]` - Check if environment variable is set -- **Build type**: `[debug]`, `[release]` - Based on compilation mode +- **Platform**: `[unix]`, `[windows]`, `[linux]`, `[darwin]` +- **Network**: `[net]` - Automatically detected +- **Programs**: `[exec:program]` - 35+ common programs auto-detected (git, docker, python, etc.) +- **Environment**: `[env:VAR]` - Dynamic environment variable checking +- **Build**: `[debug]`, `[release]` #### Using Conditions in Test Scripts diff --git a/src/lib.rs b/src/lib.rs index b36bea9..6b85d16 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -70,16 +70,36 @@ fn run(params: &mut RunParams, test_data_glob: &str) -> Result<()> { /// Builder for configuring and running testscript tests /// /// This provides a fluent interface for setting up and executing test scripts. +/// Network detection and 35+ common programs are automatically detected by default. /// -/// # Examples +/// ## Automatic Condition Detection /// +/// The following conditions are automatically available without any setup: +/// +/// - **Platform conditions**: `[unix]`, `[windows]`, `[linux]`, `[darwin]`, `[macos]` +/// - **Network condition**: `[net]` - Tests network connectivity by pinging reliable hosts +/// - **Build conditions**: `[debug]`, `[release]` - Based on compilation flags +/// - **Program conditions**: `[exec:program]` - Detects 35+ common programs including: +/// - Basic tools: cat, echo, ls, mkdir, rm, cp, mv, chmod, pwd, grep, find +/// - Development: git, make, cmake, docker, node, npm, python, go, cargo, rustc +/// - Archive: tar, gzip, zip, curl, wget, ssh, diff +/// - System: ps, kill, sleep, true, false, sh, bash, zsh +/// - **Environment conditions**: `[env:VAR]` - Dynamic checking of environment variables +/// +/// ## Examples +/// +/// ### Basic Usage /// ```no_run /// use testscript_rs::testscript; /// -/// // Simple usage +/// // Simple usage - all conditions detected automatically /// testscript::run("testdata").execute().unwrap(); +/// ``` +/// +/// ### With Custom Setup +/// ```no_run +/// use testscript_rs::testscript; /// -/// // With customization and advanced conditions /// testscript::run("testdata") /// .setup(|env| { /// // Compile your CLI tool @@ -93,26 +113,14 @@ fn run(params: &mut RunParams, test_data_glob: &str) -> Result<()> { /// // Custom command implementation /// Ok(()) /// }) -/// .condition("net", check_network_available()) -/// .condition("docker", command_exists("docker")) -/// .condition("env:CI", std::env::var("CI").is_ok()) +/// .condition("custom", my_custom_check()) /// .execute() /// .unwrap(); /// -/// // Basic usage - all common conditions detected automatically -/// testscript::run("testdata") -/// .execute() -/// .unwrap(); -/// -/// fn check_network_available() -> bool { -/// // Your network check implementation +/// fn my_custom_check() -> bool { +/// // Your custom condition logic /// true /// } -/// -/// fn command_exists(cmd: &str) -> bool { -/// // Your command existence check -/// false -/// } /// ``` pub struct Builder { dir: String, @@ -152,7 +160,35 @@ impl Builder { /// Set a condition value for conditional command execution /// - /// Conditions can be used in test scripts like `[mycondition] exec echo hello` + /// Use this to add custom conditions beyond the built-in ones. + /// Many common conditions are automatically detected (see Builder docs for details). + /// + /// # Arguments + /// * `name` - The condition name (use in scripts as `[name]`) + /// * `value` - Whether the condition is met + /// + /// # Built-in Conditions (automatically available) + /// - `net` - Network connectivity + /// - `unix`, `windows`, `linux`, `darwin` - Platform detection + /// - `debug`, `release` - Build type + /// - `exec:program` - Program availability (35+ programs) + /// - `env:VAR` - Environment variables (dynamic) + /// + /// # Examples + /// ```no_run + /// use testscript_rs::testscript; + /// + /// testscript::run("testdata") + /// .condition("feature_enabled", cfg!(feature = "advanced")) + /// .condition("has_gpu", check_gpu_available()) + /// .execute() + /// .unwrap(); + /// + /// fn check_gpu_available() -> bool { + /// // Your GPU detection logic + /// false + /// } + /// ``` pub fn condition(mut self, name: &str, value: bool) -> Self { self.params = self.params.condition(name, value); self