Crate bintest

Testing the executables build by a bin crate.

Description

cargo test has no support for running tests on a build excecutable. This crate works around this deficiency.

How It Works

There are some problems to overcome the cargo limitations.

1. Running cargo tests does not depend on the executables to be build, by default they are not compiled at test time.
2. There are no standard facilities to locate and execute them in a test.

BinTest solve these problems by running cargo build at test time, parsing its output for identifying and locating the build executables. On request it creates a std::process::Command for the binary which can be used for any further testing.

Example

In simple cases you can just call BinTest::new() to build all executables in the current crate and get a reference to a BinTest singleton to work with.

#[test]
fn test() {
  // BinTest::new() will run 'cargo build' and registers all build executables
  let executables: &'static BinTest = BinTest::new();

  // List the executables build
  for (k,v) in executables.list_executables() {
    println!("{} @ {}", k, v);
  }

  // BinTest::command() looks up executable by its name and creates a process::Command from it
  let command = executables.command("name");

  // this command can then be used for testing
  command.arg("help").spawn();
}

In more complex cases you can use the BinTest::with() to configure the build process with a BinTestBuilder and then call .build() on it to get a reference to the BinTest singleton.

See also

The testcall crate uses this to build tests and assertions on top of the commands created by bintest. The testpath crate crate lets you run test in specially created temporary directories to provide an filesystem environment for tests.

Structs

BinTest

Access to binaries build by cargo build. Starting with version 2.0.0 this is a singleton that is constructed by the first call to BinTest::new() or BinTest::with().build(). All calls to BinTest must be configured with the same configuration values, otherwise a panic will occur. This is made in anticipation of future versions which will allow building binary artifacts with different configurations while not panicking then.

BinTestBuilder

Allows configuration of a workspace to find an executable in.

Command

A process builder, providing fine-grained control over how a new process should be spawned.

Stdio

Describes what to do with a standard I/O stream for a child process when passed to the stdin, stdout, and stderr methods of Command.

Utf8PathBuf

An owned, mutable UTF-8 path (akin to String).