Struct BinProcessBuilder 

pub struct BinProcessBuilder { /* private fields */ }

Start a running process of a binary.

All tracing events emitted by your binary in JSON over stdout will be processed by BinProcess and then emitted to the tests stdout in the default human readable tracing format. To ensure any WARN/ERROR’s from your test logic are visible, BinProcess will setup its own subscriber that outputs to the tests stdout in the default human readable format. If you set your own subscriber before constructing a BinProcess that will take preference instead.

Dropping the BinProcess will trigger a panic unless BinProcess::shutdown_and_then_consume_events or BinProcess::consume_remaining_events has been called. This is done to avoid missing important assertions run by those methods.

Which constructor to use:

A guide to constructing BinProcess based on your use case:

You are writing an integration test or bench and the binary you want to run is defined in the same package as the test or bench you are writing.

Use BinProcessBuilder::from_path like this:

BinProcessBuilder::from_path(bin_path!("cooldb"))
    .with_args(vec!["--log-format".to_owned(), "json".to_owned()])
    .start()
    .await;

Using from_path instead of from_cargo_name here is faster and more robust as BinProcess does not need to invoke Cargo.

You are writing an integration test or bench and the binary you want to test is in the same

workspace but in a different package to the test or bench you are writing. Use BinProcessBuilder::from_cargo_name like this:

BinProcessBuilder::from_cargo_name("cooldb".to_owned(), None)
    .with_args(vec!["--log-format".to_owned(), "json".to_owned()])
    .start()
    .await;

You are writing an example or other binary within a package

Use BinProcessBuilder::from_cargo_name like this:

BinProcessBuilder::from_cargo_name("cooldb".to_owned(), None)
    .with_args(vec!["--log-format".to_owned(), "json".to_owned()])
    .start()
    .await;

You need to compile the binary with an arbitrary profile

Use BinProcessBuilder::from_cargo_name like this:

BinProcessBuilder::from_cargo_name("cooldb".to_owned(), Some("profilename".to_owned()))
    .with_args(vec!["--log-format".to_owned(), "json".to_owned()])
    .start()
    .await;

You have an arbitrary pre-compiled binary to run

Use BinProcessBuilder::from_path like this:

BinProcessBuilder::from_path(PathBuf::from("some/path/to/precompiled/cooldb"))
    .with_args(vec!["--log-format".to_owned(), "json".to_owned()])
    .start()
    .await;

Implementations

impl BinProcessBuilder

pub fn from_path(bin_path: PathBuf) -> Self

Start the binary specified in bin_path.

Make sure to also call with_args or with_env_vars to enable the tracing JSON logger to stdout if that is not the default.

pub fn from_cargo_name(name: String, profile: Option<String>) -> Self

Prefer BinProcessBuilder::from_path where possible as it is faster and more robust.

Start the binary named cargo_bin_name in the current workspace in a new process. A BinProcess is returned which can be used to interact with the process.

The crate will be compiled with the Cargo profile specified in cargo_profile.

• When it is Some(_) the value specified is used.
• When it is None it will use “release” if tokio-bin-process was compiled in a release derived profile or “dev” if it was compiled in a dev derived profile.

The reason None will only ever result in a “release” or “dev” profile is due to a limitation on what profile information Cargo exposes to us.

Make sure to also call with_args or with_env_vars to enable the tracing JSON logger to stdout if that is not the default.

pub fn with_log_name(self, log_name: Option<String>) -> Self

log_name is prepended to the logs that BinProcess forwards to stdout. This helps to differentiate between tracing logs generated by the test itself and the process under test. The log name must be <= 10 characters.

pub fn with_args(self, args: Vec<String>) -> Self

The args will be used as the args to the binary. The args should give the desired setup for the given integration test.

pub fn with_env_vars(self, env_vars: Vec<(String, String)>) -> Self

The env_vars will be used as the env vars given to the binary. The env vars should give the desired setup for the given integration test.

pub async fn start(self) -> BinProcess

Start the binary specified by from_path or from_cargo_name