Struct TestChild

pub struct TestChild<T> {
    pub dir: Option<T>,
    pub cmd: String,
    pub command_path: String,
    pub child: Option<Child>,
    pub stdout: Option<Box<dyn IteratorDebug<Item = Result<String>> + Send>>,
    pub stderr: Option<Box<dyn IteratorDebug<Item = Result<String>> + Send>>,
    failure_regexes: RegexSet,
    ignore_regexes: RegexSet,
    pub deadline: Option<Instant>,
    pub timeout: Option<Duration>,
    bypass_test_capture: bool,
}

A test command child process.

Fields

dir: Option<T>

The working directory of the command.

None when the command has been waited on, and its output has been taken.

cmd: String

The full command string, including arguments and working directory.

command_path: String

The path of the command, as passed to spawn2().

child: Option<Child>

The child process itself.

None when the command has been waited on, and its output has been taken.

stdout: Option<Box<dyn IteratorDebug<Item = Result<String>> + Send>>

The standard output stream of the child process.

TODO: replace with `Option<ChildOutput { stdout, stderr }>.

stderr: Option<Box<dyn IteratorDebug<Item = Result<String>> + Send>>

The standard error stream of the child process.

failure_regexes: RegexSet

Command outputs which indicate test failure.

This list of regexes is matches against stdout or stderr, in every method that reads command output.

If any line matches any failure regex, the test fails.

ignore_regexes: RegexSet

Command outputs which are ignored when checking for test failure. These regexes override failure_regexes.

This list of regexes is matches against stdout or stderr, in every method that reads command output.

If a line matches any ignore regex, the failure regex check is skipped for that line.

deadline: Option<Instant>

The deadline for this command to finish.

Only checked when the command outputs each new line (#1140).

timeout: Option<Duration>

The timeout for this command to finish.

Only used for debugging output.

bypass_test_capture: bool

If true, write child output directly to standard output, bypassing the Rust test harness output capture.

Implementations

impl<T> TestChild<T>

pub fn with_failure_regex_set<F, X>( self, failure_regexes: F, ignore_regexes: X, ) -> Self

where F: ToRegexSet, X: ToRegexSet,

Sets up command output so each line is checked against a failure regex set, unless it matches any of the ignore regexes.

The failure regexes are ignored by wait_with_output.

To never match any log lines, use RegexSet::empty().

This method is a TestChild::with_failure_regexes wrapper for strings, Regexes, and [RegexSet]s.

Panics

• adds a panic to any method that reads output, if any stdout or stderr lines match any failure regex

pub fn with_failure_regex_iter<F, X>( self, failure_regexes: F, ignore_regexes: X, ) -> Self

where F: CollectRegexSet, X: CollectRegexSet,

Sets up command output so each line is checked against a failure regex set, unless it matches any of the ignore regexes.

The failure regexes are ignored by wait_with_output.

To never match any log lines, use NO_MATCHES_REGEX_ITER.

This method is a TestChild::with_failure_regexes wrapper for regular expression iterators.

Panics

• adds a panic to any method that reads output, if any stdout or stderr lines match any failure regex

pub fn with_failure_regexes( self, failure_regexes: RegexSet, ignore_regexes: impl Into<Option<RegexSet>>, ) -> Self

Sets up command output so each line is checked against a failure regex set, unless it matches any of the ignore regexes.

The failure regexes are ignored by wait_with_output.

Panics

• adds a panic to any method that reads output, if any stdout or stderr lines match any failure regex

pub fn apply_failure_regexes_to_outputs(&mut self)

Applies the failure and ignore regex sets to command output.

The failure regexes are ignored by wait_with_output.

Panics

• adds a panic to any method that reads output, if any stdout or stderr lines match any failure regex

fn map_into_string_lines<R>( &self, reader: R, ) -> Box<dyn IteratorDebug<Item = Result<String>> + Send>

where R: Read + Debug + Send + 'static,

Maps a reader into a string line iterator, and applies the failure and ignore regex sets to it.

pub fn kill(&mut self, ignore_exited: bool) -> Result<()>

Kill the child process.

If ignore_exited is true, log “can’t kill an exited process” errors, rather than returning them.

Returns the result of the kill.

BUGS

On Windows (and possibly macOS), this function can return Ok for processes that have panicked. See #1781.

pub fn kill_and_consume_output(&mut self, ignore_exited: bool) -> Result<()>

Kill the process, and consume all its remaining output.

If ignore_exited is true, log “can’t kill an exited process” errors, rather than returning them.

Returns the result of the kill.

pub fn kill_and_return_output(&mut self, ignore_exited: bool) -> Result<String>

Kill the process, and return all its remaining standard output and standard error output.

If ignore_exited is true, log “can’t kill an exited process” errors, rather than returning them.

Returns Ok(output), or an error if the kill failed.

pub fn wait_for_stdout_line<OptS>(&mut self, write_context: OptS) -> bool

where OptS: Into<Option<String>>,

Waits until a line of standard output is available, then consumes it.

If there is a line, and write_context is Some, writes the context to the test logs. Always writes the line to the test logs.

Returns true if a line was available, or false if the standard output has finished.

pub fn wait_for_stderr_line<OptS>(&mut self, write_context: OptS) -> bool

where OptS: Into<Option<String>>,

Waits until a line of standard error is available, then consumes it.

If there is a line, and write_context is Some, writes the context to the test logs. Always writes the line to the test logs.

Returns true if a line was available, or false if the standard error has finished.

fn wait_and_return_output_line( output: impl Iterator<Item = Result<String>>, bypass_test_capture: bool, ) -> Option<String>

Waits until a line of output is available, then returns it.

If there is a line, and write_context is Some, writes the context to the test logs. Always writes the line to the test logs.

Returns true if a line was available, or false if the standard output has finished.

pub fn wait_with_output(self) -> Result<TestOutput<T>>

Waits for the child process to exit, then returns its output.

Correctness

The other test child output methods take one or both outputs, making them unavailable to this method.

Ignores any configured timeouts.

Returns an error if the child has already been taken. TODO: return an error if both outputs have already been taken.

pub fn with_timeout(self, timeout: Duration) -> Self

Set a timeout for expect_stdout_line_matches or expect_stderr_line_matches.

Does not apply to wait_with_output.

pub fn bypass_test_capture(self, cond: bool) -> Self

Configures this test runner to forward stdout and stderr to the true stdout, rather than the fakestdout used by cargo tests.

pub fn expect_stdout_line_matches<R>( &mut self, success_regex: R, ) -> Result<String>

where R: ToRegexSet + Debug,

Checks each line of the child’s stdout against any regex in success_regex, and returns the first matching line. Prints all stdout lines.

Kills the child on error, or after the configured timeout has elapsed. See Self::expect_line_matching_regex_set for details.

pub fn expect_stderr_line_matches<R>( &mut self, success_regex: R, ) -> Result<String>

where R: ToRegexSet + Debug,

Checks each line of the child’s stderr against any regex in success_regex, and returns the first matching line. Prints all stderr lines to stdout.

Kills the child on error, or after the configured timeout has elapsed. See Self::expect_line_matching_regex_set for details.

pub fn expect_stdout_line_matches_all_unordered<RegexList>( &mut self, unordered_regexes: RegexList, ) -> Result<Vec<String>>

where RegexList: IntoIterator + Debug, RegexList::Item: ToRegexSet,

Checks each line of the child’s stdout, until it finds every regex in unordered_regexes, and returns all lines matched by any regex, until each regex has been matched at least once. If the output finishes or the command times out before all regexes are matched, returns an error with a list of unmatched regexes. Prints all stdout lines.

Kills the child on error, or after the configured timeout has elapsed. See Self::expect_line_matching_regex_set for details.

pub fn expect_stderr_line_matches_all_unordered<RegexList>( &mut self, unordered_regexes: RegexList, ) -> Result<Vec<String>>

where RegexList: IntoIterator + Debug, RegexList::Item: ToRegexSet,

Checks each line of the child’s stderr, until it finds every regex in unordered_regexes, and returns all lines matched by any regex, until each regex has been matched at least once. If the output finishes or the command times out before all regexes are matched, returns an error with a list of unmatched regexes. Prints all stderr lines.

Kills the child on error, or after the configured timeout has elapsed. See Self::expect_line_matching_regex_set for details.

pub fn expect_stdout_line_matches_silent<R>( &mut self, success_regex: R, ) -> Result<String>

where R: ToRegexSet + Debug,

Checks each line of the child’s stdout against success_regex, and returns the first matching line. Does not print any output.

Kills the child on error, or after the configured timeout has elapsed. See Self::expect_line_matching_regex_set for details.

pub fn expect_stderr_line_matches_silent<R>( &mut self, success_regex: R, ) -> Result<String>

where R: ToRegexSet + Debug,

Checks each line of the child’s stderr against success_regex, and returns the first matching line. Does not print any output.

Kills the child on error, or after the configured timeout has elapsed. See Self::expect_line_matching_regex_set for details.

pub fn expect_line_matching_regex_set<L, R>( &mut self, lines: &mut L, success_regexes: R, stream_name: &str, write_to_logs: bool, ) -> Result<String>

where L: Iterator<Item = Result<String>>, R: ToRegexSet,

Checks each line in lines against a regex set, and returns Ok if a line matches.

Self::expect_line_matching_regexes wrapper for strings, Regexes, and [RegexSet]s.

pub fn expect_line_matching_regex_iter<L, I>( &mut self, lines: &mut L, success_regexes: I, stream_name: &str, write_to_logs: bool, ) -> Result<String>

where L: Iterator<Item = Result<String>>, I: CollectRegexSet,

Checks each line in lines against a regex set, and returns Ok if a line matches.

Self::expect_line_matching_regexes wrapper for regular expression iterators.

pub fn expect_line_matching_regexes<L>( &mut self, lines: &mut L, success_regexes: RegexSet, stream_name: &str, write_to_logs: bool, ) -> Result<String>

where L: Iterator<Item = Result<String>>,

Checks each line in lines against success_regexes, and returns Ok if a line matches. Uses stream_name as the name for lines in error reports.

Kills the child on error, or after the configured timeout has elapsed.

Note: the timeout is only checked after each full line is received from the child (#1140).

fn write_to_test_logs<S>(line: S, bypass_test_capture: bool)

where S: AsRef<str>,

Write line to stdout, so it can be seen in the test logs.

Use bypass_test_capture(true) or cargo test -- --nocapture to see this output.

May cause weird reordering for stdout / stderr. Uses stdout even if the original lines were from stderr.

pub fn kill_on_error<V, E>( self, result: Result<V, E>, ) -> Result<(V, Self), Report>

where E: Into<Report> + Send + Sync + 'static,

Kill child, wait for its output, and use that output as the context for an error report based on error.

fn past_deadline(&self) -> bool

pub fn is_running(&mut self) -> bool

Is this process currently running?

Bugs

On Windows and macOS, this function can return true for processes that have panicked. See #1781.

Panics

If the child process was already been taken using wait_with_output.

Trait Implementations

impl<T> AsMut<TestChild<T>> for TestChild<T>

fn as_mut(&mut self) -> &mut Self

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T> AsRef<TestChild<T>> for TestChild<T>

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> ContextFrom<&mut TestChild<T>> for Report

type Return = Report

fn context_from(self, source: &mut TestChild<T>) -> Self::Return

impl<T: Debug> Debug for TestChild<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Drop for TestChild<T>

fn drop(&mut self)

Executes the destructor for this type.