# Crate cargo_test_support

source ·
Expand description

## §Cargo test support.

See https://rust-lang.github.io/cargo/contrib/ for a guide on writing tests.

There are two places you can find API documentation

- https://docs.rs/cargo-test-support: targeted at external tool developers testing cargo-related code
  - Released with every rustc release
- https://doc.rust-lang.org/nightly/nightly-rustc/cargo_test_support: targeted at cargo contributors
  - Updated on each update of the `cargo` submodule in `rust-lang/rust`

WARNING: You might not want to use this outside of Cargo.

- This is designed for testing Cargo itself. Use at your own risk.
- No guarantee on any stability across versions.
- No feature request would be accepted unless proved useful for testing Cargo.

## §Example

    use cargo_test_support::prelude::*;
    use cargo_test_support::str;
    use cargo_test_support::project;

    #[cargo_test]
    fn some_test() {
        let p = project()
            .file("src/main.rs", r#"fn main() { println!("hi!"); }"#)
            .build();

        p.cargo("run --bin foo")
            .with_stderr_data(str![[r#"
    [COMPILING] foo [..]
    [FINISHED] [..]
    [RUNNING] `target/debug/foo`
    "#]])
            .with_stdout_data(str![["hi!"]])
            .run();
    }

## Modules§

- compare
  Routines for comparing and diffing output.
- containers
  Support for testing using Docker containers.
- cross_compile
  Support for cross-compile tests with the `--target` flag.
- diff 🔒
  A simple Myers diff implementation.
- git
  Git Testing Support
- install
  Helpers for testing `cargo install`
- paths
  Access common paths and manipulate the filesystem
- prelude
- publish
  Helpers for testing `cargo package` / `cargo publish`
- registry
  Interact with the `TestRegistry`
- tools
  Common executables that can be reused by various tests.

## Macros§

- file
  Declare an expected value for an assert from a file
- str
  Declare an expected value from within Rust source
- t
  Unwrap a `Result` with a useful panic message

## Structs§

- Execs
  Run and verify a `ProcessBuilder`
- FileBuilder 🔒
- ProcessBuilder
  A builder object for an external process, similar to `std::process::Command`.
- Project
  A cargo project to run tests against.
- ProjectBuilder
  Create a project to run tests against
- RawOutput 🔒
  This is the raw output from the process.
- RustcInfo 🔒
- SymlinkBuilder 🔒

## Traits§

- ArgLineCommandExt
  Add a list of arguments as a line
- CargoCommandExt
  Test the cargo command
- ChannelChangerCommandExt
  Enable nightly features for testing
- TestEnvCommandExt
  Establish a process’s test environment

## Functions§

- _process 🔒
- basic_bin_manifest
  Generate a `Cargo.toml` with the specified `bin.name`
- basic_lib_manifest
  Generate a `Cargo.toml` with the specified `lib.name`
- basic_manifest
  Generate a basic `Cargo.toml`
- cargo_exe
  Path to the cargo binary
- cargo_process
  Run `cargo $arg_line`, see `Execs`
- execs
  Run and verify a process, see `Execs`
- git_process
  Run `git $arg_line`, see `ProcessBuilder`
- is_coarse_mtime
  Returns `true` if the local filesystem has low-resolution mtimes.
- is_nightly
- main_file
  Generate a `main.rs` printing the specified text
- no_such_file_err_msg
  The error message for ENOENT.
- panic_error
  `panic!`, reporting the specified error , see also `t!`
- process
  Run `$bin` in the test’s environment, see `ProcessBuilder`
- project
  Generates a project layout, see `ProjectBuilder`
- project_in
  Generates a project layout in given directory, see `ProjectBuilder`
- project_in_home
  Generates a project layout inside our fake home dir, see `ProjectBuilder`
- retry
  Helper to retry a function `n` times.
- rustc_host
  The rustc host such as `x86_64-unknown-linux-gnu`.
- rustc_host_env
  The host triple suitable for use in a cargo environment variable (uppercased).
- rustc_info 🔒
- sleep_ms
- slow_cpu_multiplier
  Some CI setups are much slower then the equipment used by Cargo itself. Architectures that do not have a modern processor, hardware emulation, etc. This provides a way for those setups to increase the cut off for all the time based test.
- symlink_supported
- thread_wait_timeout
  Helper that waits for a thread to finish, up to `n` tenths of a second.
- threaded_timeout
  Helper that runs some function, and waits up to `n` tenths of a second for it to finish.

## Attribute Macros§

- cargo_test
  Replacement for `#[test]`