Struct tokio_bin_process::BinProcess
source · pub struct BinProcess { /* private fields */ }
Expand description
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_binary_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_binary_name
like this:
BinProcess::start_binary_name(
"cooldb",
"cooldb",
&["--log-format", "json"],
None
).await;
§You are writing an example or other binary within a package
Use BinProcess::start_binary_name
like this:
BinProcess::start_binary_name(
"cooldb",
"cooldb",
&["--log-format", "json"],
None
).await;
§You need to compile the binary with an arbitrary profile
Use BinProcess::start_binary_name
like this:
BinProcess::start_binary_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§
source§impl BinProcess
impl BinProcess
sourcepub async fn start_binary_name(
cargo_bin_name: &str,
log_name: &str,
binary_args: &[&str],
cargo_profile: Option<&str>
) -> BinProcess
pub async fn start_binary_name( cargo_bin_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 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.
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” iftokio-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.
sourcepub async fn start_binary(
bin_path: &Path,
log_name: &str,
binary_args: &[&str]
) -> BinProcess
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.
sourcepub fn pid(&self) -> i32
pub fn pid(&self) -> i32
Return the PID of
TODO: when nix crate is 1.0 this method should return a nix::unistd::Pid
instead of an i32
sourcepub fn send_sigterm(&self)
pub fn send_sigterm(&self)
Send SIGTERM to the process
TODO: This will be replaced with a send_signal
method when nix crate is 1.0
sourcepub fn send_sigint(&self)
pub fn send_sigint(&self)
Send SIGINT to the process
TODO: This will be replaced with a send_signal
method when nix crate is 1.0
sourcepub async fn wait_for(
&mut self,
ready: &EventMatcher,
expected_errors_and_warnings: &[EventMatcher]
) -> Events
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.
sourcepub async fn consume_events(
&mut self,
event_count: usize,
expected_errors_and_warnings: &[EventMatcher]
) -> Events
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.
sourcepub async fn shutdown_and_then_consume_events(
self,
expected_errors_and_warnings: &[EventMatcher]
) -> Events
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.
sourcepub async fn consume_remaining_events(
self,
expected_errors_and_warnings: &[EventMatcher]
) -> Events
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.
sourcepub async fn consume_remaining_events_expect_failure(
self,
expected_errors_and_warnings: &[EventMatcher]
) -> Events
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