Crate cargo_test_support

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

This crate is maintained by the Cargo team, primarily for use by Cargo and not intended for external use. This crate may make major changes to its APIs or be deprecated without warning.

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.

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 🔒

assert_deps

assert_deps_contains

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

A way for 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]