trycmd

https://docs.rs/trycmd/latest/trycmd/
Admin
trycmd is a Rust test harness that enumerates CLI test case files and runs them to verify snapshot...
Tokens:40,423
Snippets:243
Trust Score:9.1
Update:1 day ago
Show doc for...
Tokens:
Raw
### compile_examples

Source: https://docs.rs/trycmd/latest/trycmd/cargo/fn.compile_examples.html

Prepares all examples for testing. Unlike `cargo_bin!`, it does not inherit all current compiler settings; it matches the current target and profile but does not get feature flags. Pass those arguments to the compiler via `args`.

```APIDOC
## compile_examples

### Description
Prepares all examples for testing. Unlike `cargo_bin!`, this does not inherit all of the current compiler settings. It will match the current target and profile but will not get feature flags. Pass those arguments to the compiler via `args`.

### Function Signature
```rust
pub fn compile_examples<'a>(
    args: impl IntoIterator<Item = &'a str>,
) -> Result<impl Iterator<Item = (String, Bin)>, Error>
```

### Parameters
- **args** (`impl IntoIterator<Item = &'a str>`) - Required - Compiler arguments to pass to the compiler.

### Return Value
- `Result<impl Iterator<Item = (String, Bin)>, Error>` - An iterator of tuples containing a `String` (binary name) and a `Bin` object, or an `Error`.

### Availability
Available on **crate feature `examples`** only.

### Example
```rust
#[test]
fn cli_tests() {
    trycmd::TestCases::new()
        .register_bins(trycmd::cargo::compile_examples([]).unwrap())
        .case("examples/cmd/*.trycmd");
}
```
```

--------------------------------

### compile_examples

Source: https://docs.rs/trycmd/latest/trycmd/cargo/index.html

Function to prepare all examples for testing.

```APIDOC
## compile_examples

### Description
Prepare all examples for testing.

### Signature
`pub fn compile_examples() -> Vec<PathBuf>`

### Returns
- `Vec<PathBuf>` - A vector of paths to all compiled example binaries.

```

--------------------------------

### Example usage of compile_examples in a test

Source: https://docs.rs/trycmd/latest/trycmd/cargo/fn.compile_examples.html

Example test that registers compiled examples with `TestCases` and runs a case on `examples/cmd/*.trycmd`. This shows how to use `compile_examples` in a test.

```rust
#[test]
fn cli_tests() {
    trycmd::TestCases::new()
        .register_bins(trycmd::cargo::compile_examples([]).unwrap())
        .case("examples/cmd/*.trycmd");
}
```

--------------------------------

### compile_example

Source: https://docs.rs/trycmd/latest/trycmd/cargo/fn.compile_example.html

Prepares an example for testing by compiling it with the given arguments. It matches the current target and profile but does not inherit feature flags, so those must be passed via args.

```APIDOC
## compile_example

### Description
Prepares an example for testing. Unlike `cargo_bin!`, this does not inherit all of the current compiler settings. It will match the current target and profile but will not get feature flags. Pass those arguments to the compiler via `args`.

### Function Signature
```rust
pub fn compile_example<'a>(
    target_name: &str,
    args: impl IntoIterator<Item = &'a str>,
) -> Bin
```

### Parameters
- **target_name** (&str) - Required - The name of the example target to compile.
- **args** (impl IntoIterator<Item = &'a str>) - Required - Compiler arguments to pass, such as feature flags.

### Return Value
- **Bin** - The compiled example binary.

### Availability
Available on **crate feature `examples`** only.

### Example
```rust
#[test]
fn cli_tests() {
    trycmd::TestCases::new()
        .register_bin("example-fixture", trycmd::cargo::compile_example("example-fixture", []))
        .case("examples/cmd/*.trycmd");
}
```
```

--------------------------------

### cargo::compile_examples

Source: https://docs.rs/trycmd/latest/trycmd/all.html

Function that compiles all example binaries for testing.

```APIDOC
## cargo::compile_examples

### Description
Compiles all example binaries for testing.

### Function
`cargo::compile_examples`

### Returns
- `Vec<PathBuf>` - A list of paths to the compiled examples.

```

--------------------------------

### Rust binary example for trycmd test

Source: https://docs.rs/trycmd/latest/trycmd/

A minimal Rust main function that prints 'Hello world'. This is the binary that the trycmd test case will invoke.

```rust
fn main() {
    println!("Hello world");
}
```

--------------------------------

### cargo::compile_example

Source: https://docs.rs/trycmd/latest/trycmd/all.html

Function that compiles a single example binary for testing.

```APIDOC
## cargo::compile_example

### Description
Compiles a single example binary for testing.

### Function
`cargo::compile_example`

### Parameters
- `name` (string) - Required - The name of the example.

### Returns
- `PathBuf` - The path to the compiled example.

```

--------------------------------

### Using compile_example in a Test

Source: https://docs.rs/trycmd/latest/trycmd/cargo/fn.compile_example.html

Example test that registers a compiled example binary with trycmd::TestCases. Note that compile_example does not inherit feature flags; pass them via args.

```rust
#[test]
fn cli_tests() {
    trycmd::TestCases::new()
        .register_bin("example-fixture", trycmd::cargo::compile_example("example-fixture", []))
        .case("examples/cmd/*.trycmd");
}
```

--------------------------------

### Minimal trycmd test setup in tests/cli_tests.rs

Source: https://docs.rs/trycmd/latest/trycmd/

Creates a TestCases instance and adds test cases from TOML files and a README.md. Run with cargo test to enumerate and verify commands.

```rust
#[test]
fn cli_tests() {
    trycmd::TestCases::new()
        .case("tests/cmd/*.toml")
        .case("README.md");
}
```

--------------------------------

### Example usage of cargo_bin in a test

Source: https://docs.rs/trycmd/latest/trycmd/cargo/macro.cargo_bin.html

Example test function that uses trycmd::cargo_bin! to set the default binary path for test cases.

```rust
#[test]
fn cli_tests() {
    trycmd::TestCases::new()
        .default_bin_path(trycmd::cargo_bin!("bin-fixture"))
        .case("tests/cmd/*.trycmd");
}
```

--------------------------------

### compile_example Function Signature

Source: https://docs.rs/trycmd/latest/trycmd/cargo/fn.compile_example.html

Signature of compile_example. It takes a target name and an iterator of arguments, returning a Bin. Available only with the 'examples' feature.

```rust
pub fn compile_example<'a>(
    target_name: &str,
    args: impl IntoIterator<Item = &'a str>,
) -> Bin
```

--------------------------------

### Function signature: compile_examples

Source: https://docs.rs/trycmd/latest/trycmd/cargo/fn.compile_examples.html

Signature of the `compile_examples` function. It accepts an iterator of string arguments and returns a result with an iterator of `(String, Bin)` pairs. Available only with the `examples` feature.

```rust
pub fn compile_examples<'a>(
    args: impl IntoIterator<Item = &'a str>,
) -> Result<impl Iterator<Item = (String, Bin)>, Error>
```

--------------------------------

### Example: Using insert_var in a test

Source: https://docs.rs/trycmd/latest/trycmd/struct.TestCases.html

Shows how to use TestCases::insert_var to add a normalization variable. The variable name must be surrounded by [] and consist of uppercase letters. Variables are preserved through TRYCMD=overwrite/dump.

```rust
#[test]
fn cli_tests() {
    trycmd::TestCases::new()
        .case("tests/cmd/*.trycmd")
        .insert_var("[VAR]", "value");
}
```

--------------------------------

### trycmd console test case

Source: https://docs.rs/trycmd/latest/trycmd/

A literate test case in Markdown fenced code block with console language. The '$' prefix starts a command, and the following lines are expected stdout/stderr. The command is split with shlex.

```markdown
```console
$ my-cmd
Hello world

```
```

--------------------------------

### run

Source: https://docs.rs/trycmd/latest/trycmd/struct.TestCases.html

Runs the tests. This happens automatically on drop if not called explicitly.

```APIDOC
## run

### Description
Runs the tests. This will happen on `drop` if not done explicitly.

### Method
run

### Signature
pub fn run(&self)

### Parameters
None.

### Returns
None.

### Example
```rust
let cases = trycmd::TestCases::new();
cases.run();
```
```

--------------------------------

### TestCases::new

Source: https://docs.rs/trycmd/latest/trycmd/struct.TestCases.html

Creates a new TestCases instance for running tests.

```APIDOC
## TestCases::new

### Description
Creates a new TestCases instance for running tests.

### Method
`pub fn new() -> Self`

### Parameters
None

### Returns
- `Self` - A new TestCases instance.
```

--------------------------------

### impl Serialize for Env

Source: https://docs.rs/trycmd/latest/trycmd/schema/struct.Env.html

Enables serialization of Env instances using Serde.

```APIDOC
## impl Serialize for Env

### Description
Enables serialization of Env instances using Serde.

### Methods

#### fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer
Serialize this value into the given Serde serializer.

```

--------------------------------

### register_bin

Source: https://docs.rs/trycmd/latest/trycmd/struct.TestCases.html

Adds a single binary to the PATH for test cases to use.

```APIDOC
## register_bin

### Description
Adds a binary to the PATH so that test cases can invoke it.

### Method
register_bin

### Signature
pub fn register_bin(&self, name: impl Into<String>, path: impl Into<Bin>) -> &Self

### Parameters
- **name** (impl Into<String>) - Required - The name of the binary.
- **path** (impl Into<Bin>) - Required - The path to the binary.

### Returns
- **&Self** - The TestCases instance for chaining.

### Example
```rust
let cases = trycmd::TestCases::new();
cases.register_bin("mybin", "path/to/bin");
```
```

--------------------------------

### impl<Q, K> Equivalent<K> for Q (equivalent)

Source: https://docs.rs/trycmd/latest/trycmd/struct.Error.html

Implementation of the equivalent crate's Equivalent trait for Q where K: Borrow<Q>. Provides the equivalent method to compare self to a key.

```APIDOC
## Trait Implementation: Equivalent<K> for Q (equivalent)

### Description
Implementation of the `equivalent::Equivalent` trait for `Q` where `K: Borrow<Q>`. This allows comparing a value to a key for equality.

### Method
`equivalent`

### Signature
`fn equivalent(&self, key: &K) -> bool`

### Parameters
- **key** (`&K`) - The key to compare against.

### Returns
- **bool** - `true` if `self` is equal to `key`, `false` otherwise.

### Description
Compare self to `key` and return `true` if they are equal.
```

--------------------------------

### impl PartialEq for Env

Source: https://docs.rs/trycmd/latest/trycmd/schema/struct.Env.html

Provides equality comparison for Env instances using the == and != operators.

```APIDOC
## impl PartialEq for Env

### Description
Provides equality comparison for Env instances using the == and != operators.

### Methods

#### fn eq(&self, other: &Self) -> bool
Equality operator `==`.

#### fn ne(&self, other: &Rhs) -> bool
Inequality operator `!=`.

```

--------------------------------

### TestCases

Source: https://docs.rs/trycmd/latest/trycmd/

Entry point for running tests. This struct is used to configure and execute test cases for command-line applications.

```APIDOC
## TestCases

### Description
Entry point for running tests. This struct is used to configure and execute test cases for command-line applications.

### Usage
This struct is the primary interface for defining and running tests in trycmd. Users can create an instance of `TestCases` and use its methods to add test cases and run them.

### Methods
- **run()** - Executes the configured test cases.
- **case()** - Adds a test case to the test suite.

### Example
```rust
use trycmd::TestCases;

#[test]
fn test() {
    let mut cases = TestCases::new();
    cases.case("examples/*.md");
    cases.run();
}
```
```

--------------------------------

### Generate snapshots with TRYCMD=dump

Source: https://docs.rs/trycmd/latest/trycmd/

Runs cargo test with TRYCMD=dump to write .stdout and .stderr files into a dump/ directory.

```console
$ TRYCMD=dump cargo test --test cli_tests
```

--------------------------------

### TestCases::default_bin_path

Source: https://docs.rs/trycmd/latest/trycmd/struct.TestCases.html

Sets the default binary path for commands.

```APIDOC
## TestCases::default_bin_path

### Description
Sets the default binary path for commands.

### Method
`pub fn default_bin_path(&self, path: impl AsRef<Path>) -> &Self`

### Parameters
- `path` (impl AsRef<Path>) - Required - The path to the default binary.

### Returns
- `&Self` - The TestCases instance for chaining.
```

--------------------------------

### register_bins

Source: https://docs.rs/trycmd/latest/trycmd/struct.TestCases.html

Adds multiple binaries to the PATH for test cases to use.

```APIDOC
## register_bins

### Description
Adds a series of binaries to the PATH for test cases to use.

### Method
register_bins

### Signature
pub fn register_bins<N: Into<String>, B: Into<Bin>>(&self, bins: impl IntoIterator<Item = (N, B)>) -> &Self

### Parameters
- **bins** (impl IntoIterator<Item = (N, B)>) - Required - An iterator of (name, path) pairs.

### Returns
- **&Self** - The TestCases instance for chaining.

### Example
```rust
let cases = trycmd::TestCases::new();
cases.register_bins([("bin1", "path1"), ("bin2", "path2")]);
```
```

--------------------------------

### impl<Q, K> Equivalent<K> for Q (hashbrown)

Source: https://docs.rs/trycmd/latest/trycmd/struct.Error.html

Implementation of the hashbrown Equivalent trait for Q where K: Borrow<Q>. Provides the equivalent method to check if a value is equivalent to a given key.

```APIDOC
## Trait Implementation: Equivalent<K> for Q (hashbrown)

### Description
Implementation of the `hashbrown::Equivalent` trait for `Q` where `K: Borrow<Q>`. This allows checking if a value is equivalent to a given key.

### Method
`equivalent`

### Signature
`fn equivalent(&self, key: &K) -> bool`

### Parameters
- **key** (`&K`) - The key to compare against.

### Returns
- **bool** - `true` if the value is equivalent to the key, `false` otherwise.

### Description
Checks if this value is equivalent to the given key.
```

--------------------------------

### Update snapshots with TRYCMD=overwrite

Source: https://docs.rs/trycmd/latest/trycmd/

Runs cargo test with TRYCMD=overwrite to overwrite existing .stdout and .stderr files in tests/cmd.

```console
$ TRYCMD=overwrite cargo test --test cli_tests
```

--------------------------------

### Module: schema

Source: https://docs.rs/trycmd/latest/trycmd/

`cmd.toml` Schema. This module defines the schema for the `cmd.toml` configuration file used by trycmd.

```APIDOC
## Module: schema

### Description
`cmd.toml` Schema. This module defines the schema for the `cmd.toml` configuration file used by trycmd.

### Usage
This module provides types and functions for parsing and validating `cmd.toml` files, which define test cases and expected outputs.

### Example
```rust
use trycmd::schema;

// Example usage of schema module
```
```

--------------------------------

### cargo_bin_opt

Source: https://docs.rs/trycmd/latest/trycmd/cargo/fn.cargo_bin_opt.html

Look up the path to a cargo-built binary within an integration test. Returns None if the binary doesn't exist. Cargo support: >1.94 works, >=1.91,<=1.93 works with default build-dir, <=1.92 works.

```APIDOC
## cargo_bin_opt

### Description
Look up the path to a cargo-built binary within an integration test. Returns `None` if the binary doesn't exist.

### Function Signature
```rust
pub fn cargo_bin_opt(name: &str) -> Option<PathBuf>
```

### Parameters
- **name** (`&str`) - The name of the binary to look up.

### Return Value
- `Option<PathBuf>` - The path to the binary if it exists, otherwise `None`.

### Cargo Support
- `>1.94`: works
- `>=1.91,<=1.93`: works with default `build-dir`
- `<=1.92`: works
```

--------------------------------

### cargo::cargo_bin (macro)

Source: https://docs.rs/trycmd/latest/trycmd/all.html

Macro that expands to the path of a cargo binary for testing.

```APIDOC
## cargo::cargo_bin (macro)

### Description
Macro that expands to the path of a cargo binary for testing.

### Macro
`cargo::cargo_bin`

### Usage
`cargo_bin!("name")`

### Parameters
- `name` (string literal) - Required - The name of the binary.

### Expansion
Expands to a `PathBuf` expression.

```

--------------------------------

### TestCases::default_bin_name

Source: https://docs.rs/trycmd/latest/trycmd/struct.TestCases.html

Sets the default binary name for commands.

```APIDOC
## TestCases::default_bin_name

### Description
Sets the default binary name for commands.

### Method
`pub fn default_bin_name(&self, name: impl AsRef<str>) -> &Self`

### Parameters
- `name` (impl AsRef<str>) - Required - The name of the default binary.

### Returns
- `&Self` - The TestCases instance for chaining.
```

--------------------------------

### Eq for Filesystem

Source: https://docs.rs/trycmd/latest/trycmd/schema/struct.Filesystem.html

Implements the Eq trait for the Filesystem struct, providing equality comparison.

```APIDOC
## Eq for Filesystem

### Description
Implements the `Eq` trait for the `Filesystem` struct, providing equality comparison.

### Trait
`Eq`

### Source
[Source](https://docs.rs/trycmd/latest/src/trycmd/schema.rs.html#757)
```

--------------------------------

### cargo_bin

Source: https://docs.rs/trycmd/latest/trycmd/cargo/fn.cargo_bin.html

Looks up the path to a cargo-built binary within an integration test. Returns a PathBuf to the binary. Panics if no binary is found.

```APIDOC
## cargo_bin

### Description
Looks up the path to a cargo-built binary within an integration test. Returns a PathBuf to the binary. Panics if no binary is found.

### Function Signature
pub fn cargo_bin(name: &str) -> PathBuf

### Parameters
- **name** (&str) - Required - The name of the binary to look up.

### Return Value
- **PathBuf** - The path to the cargo-built binary.

### Panics
Panics if no binary is found.

### Cargo Compatibility
- `>1.94`: works
- `>=1.91,<=1.93`: works with default `build-dir`
- `<=1.92`: works
```

--------------------------------

### TestCases::case

Source: https://docs.rs/trycmd/latest/trycmd/struct.TestCases.html

Loads tests from a glob pattern.

```APIDOC
## TestCases::case

### Description
Loads tests from a glob pattern.

### Method
`pub fn case(&self, glob: impl AsRef<Path>) -> &Self`

### Parameters
- `glob` (impl AsRef<Path>) - Required - The glob pattern to load test cases from.

### Returns
- `&Self` - The TestCases instance for chaining.
```

--------------------------------

### TestCases::env

Source: https://docs.rs/trycmd/latest/trycmd/struct.TestCases.html

Sets a default environment variable for commands.

```APIDOC
## TestCases::env

### Description
Sets a default environment variable for commands.

### Method
`pub fn env(&self, key: impl Into<String>, value: impl Into<String>) -> &Self`

### Parameters
- `key` (impl Into<String>) - Required - The environment variable name.
- `value` (impl Into<String>) - Required - The environment variable value.

### Returns
- `&Self` - The TestCases instance for chaining.
```
Tokens:
Raw