Struct tokio_bin_process::BinProcess

pub struct BinProcess { /* private fields */ }

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 BinProcess::start_binary like this:

BinProcess::start_binary(
    bin_path!("cooldb"),
    "cooldb",
    &["--log-format", "json"],
).await;

Using start_binary instead of start_crate_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 BinProcess::start_crate_name like this:

BinProcess::start_crate_name(
    "cooldb",
    "cooldb",
    &["--log-format", "json"],
    None
).await;

You are writing an example or other binary within a package

Use BinProcess::start_crate_name like this:

BinProcess::start_crate_name(
    "cooldb",
    "cooldb",
    &["--log-format", "json"],
    None
).await;

You need to compile the binary with an arbitrary profile

Use BinProcess::start_crate_name like this:

BinProcess::start_crate_name(
    "cooldb",
    "cooldb",
    &["--log-format", "json"],
    Some("profilename")
).await;

You have an arbitrary pre-compiled binary to run

Use BinProcess::start_binary like this:

BinProcess::start_binary(
    Path::new("some/path/to/precompiled/cooldb"),
    "cooldb",
    &["--log-format", "json"],
).await;

Implementations

impl BinProcess

pub async fn start_crate_name( cargo_crate_name: &str, log_name: &str, binary_args: &[&str], cargo_profile: Option<&str> ) -> BinProcess

Prefer BinProcess::start_binary where possible as it is faster and more robust.

Start the crate binary named cargo_crate_name in a process and returns a BinProcess which can be used to interact with the process.

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 binary_args will be used as the args to the binary. The args should give the desired setup for the given integration test and should also enable the tracing JSON logger to stdout if that is not the default.

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.

pub async fn start_binary( bin_path: &Path, log_name: &str, binary_args: &[&str] ) -> BinProcess

Start the binary specified in bin_path.

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 binary_args will be used as the args to the binary. The args should give the desired setup for the given integration test and should also enable the tracing JSON logger to stdout if that is not the default.

pub fn child(&self) -> &Child

pub fn signal(&self, signal: Signal)

pub async fn wait_for( &mut self, ready: &EventMatcher, expected_errors_and_warnings: &[EventMatcher] ) -> Events

Waits for the ready EventMatcher to match on an incoming event. All events that were encountered while waiting are returned.

pub async fn consume_events( &mut self, event_count: usize, expected_errors_and_warnings: &[EventMatcher] ) -> Events

Await event_count messages to be emitted from the process. The emitted events are returned.

pub async fn shutdown_and_then_consume_events( self, expected_errors_and_warnings: &[EventMatcher] ) -> Events

Issues SIGTERM to the process and then awaits its shutdown. All remaining events will be returned.

pub async fn consume_remaining_events( self, expected_errors_and_warnings: &[EventMatcher] ) -> Events

prefer shutdown_and_then_consume_events. This method will not return until the process has terminated. It is useful when you need to test a shutdown method other than SIGTERM.

pub async fn consume_remaining_events_expect_failure( self, expected_errors_and_warnings: &[EventMatcher] ) -> Events

Identical to consume_remaining_events but asserts that the process exited with failure code instead of success

Trait Implementations

impl Drop for BinProcess

fn drop(&mut self)

Executes the destructor for this type.