Struct regex_test::TestRunner

pub struct TestRunner { /* private fields */ }

A runner for executing regex tests.

This runner is intended to be used within a Rust unit test, marked with the #[test] attribute.

A test runner is responsible for running tests against a regex implementation. It contains logic for skipping tests and collects test results. Typical usage corresponds to calling TestRunner::test_iter on an iterator of RegexTests, and then calling assert once done. If any tests failed, then assert will panic with an error message containing all test failures. assert must be called before the test completes.

Skipping tests

If the REGEX_TEST environment variable is set, then it may contain a comma separated list of substrings. Each substring corresponds to a whitelisted item, unless it starts with a -, in which case it corresponds to a blacklisted item.

If there are any whitelist items, then a test’s full name must contain at least one of the whitelist substrings in order to be run, and does not contain and blacklist substrings. If there are no whitelist substrings, then a test is run only when it does not match any blacklist substrings.

The last substring that a test name matches takes precedent.

Callers may also specify explicit whitelist or blacklist substrings using the corresponding methods on this type, which has the effect of always having those rules in place for that specific test. For example, if you’re testing a search by building a DFA and then minimizing it, you may want to skip tests with bigger regexes, since they could take quite some time to run.

Whitelist and blacklist substrings are matched on the full name of each test, which typically looks like group_name/test_name.

Currently there is no way to escape either a - or a , in REGEX_TEST. This usually isn’t required because test names usually don’t include either character.

Implementations

impl TestRunner

pub fn new() -> Result<TestRunner>

Create a new runner for executing tests.

The test runner maintains a full list of tests that have succeeded, failed or been skipped. Moreover, the test runner may control which tests get run via its whitelist and blacklist.

This returns an error if there was a problem reading the REGEX_TEST environment variable, which may be set to include or exclude tests. See the docs on TestRunner for its format.

pub fn assert(&mut self)

Assert that all tests run have either passed or have been skipped.

If any tests have failed, then a panic occurs with a report of all failures.

If REGEX_TEST_VERBOSE is set to 1, then a longer report of tests that passed, failed or skipped is printed.

pub fn whitelist(&mut self, substring: &str) -> &mut TestRunner

Whitelist the given substring.

Whitelist and blacklist rules are only applied when TestRunner::test_iter is called.

pub fn whitelist_iter<I, S>(&mut self, substrings: I) -> &mut TestRunnerwhere I: IntoIterator<Item = S>, S: AsRef<str>,

Whitelist the given iterator substrings.

This is a convenience routine for calling whitelist on each of the substrings in the iterator provided.

Whitelist and blacklist rules are only applied when TestRunner::test_iter is called.

pub fn blacklist(&mut self, substring: &str) -> &mut TestRunner

Blacklist the given substring.

A blacklisted test is never run, unless a whitelisted substring added after the blacklisted substring matches it.

Whitelist and blacklist rules are only applied when TestRunner::test_iter is called.

pub fn blacklist_iter<I, S>(&mut self, substrings: I) -> &mut TestRunnerwhere I: IntoIterator<Item = S>, S: AsRef<str>,

Blacklist the given iterator substrings.

A blacklisted test is never run, unless a whitelisted substring added after the blacklisted substring matches it.

This is a convenience routine for calling blacklist on each of the substrings in the iterator provided.

Whitelist and blacklist rules are only applied when TestRunner::test_iter is called.

pub fn expand<S: AsRef<str>>( &mut self, additional_names: &[S], predicate: impl FnMut(&RegexTest) -> bool + 'static ) -> &mut TestRunner

Set an expansion predicate that appends each entry in additional_names to the end the name for every test that predicate returns true. Moreover, the corresponding additional name is made available via RegexTest::additional_name.

This permits implementors to create multiple copies of each test, and then do specifically different tasks with each, while making it so each test is distinct.

For example, you might write something like this:

TestRunner::new()?
    .expand(&["is_match", "find"], |t| t.compiles())
    .test_iter(tests, compiler)
    .assert()

where each test that is expected to have a regex compile gets copied with /is_match and /find appends to the end of its name. Then, in your own test runner, you can inspect RegexTest::additional_name to decide what to do. In the case of is_match, you might test your regex engines “has a match” API, which might exercise different logic than your “find where the matches are” API.

pub fn test_iter<I, T>( &mut self, it: I, compile: impl FnMut(&RegexTest, &[String]) -> Result<CompiledRegex> ) -> &mut TestRunnerwhere I: IntoIterator<Item = T>, T: Borrow<RegexTest>,

Run all of the given tests using the given regex compiler.

The compiler given is a closure that accepts a &RegexTest and a sequence of patterns, and returns (if successful) a CompiledRegex which can execute a search.

Note that if there are test failures, this merely collects them. Use TestRunner::assert to fail the current test by panicking if there any failures.

Typically, one provides RegexTests::iter as the iterator of RegexTest values.

pub fn test( &mut self, test: &RegexTest, compile: impl FnMut(&[String]) -> Result<CompiledRegex> ) -> &mut TestRunner

Run a single test.

This records the result of running the test in this runner. This does not fail the test immediately if the given regex test fails. Instead, this is only done when the assert method is called.

Note that using this method bypasses any whitelist or blacklist applied to this runner. Whitelisted (and blacklisted) substrings are only applied when using test_iter.

Trait Implementations

impl Debug for TestRunner

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

Formats the value using the given formatter.