Struct regex_test::TestRunner
source · pub struct TestRunner { /* private fields */ }
Expand description
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 RegexTest
s, 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§
source§impl TestRunner
impl TestRunner
sourcepub fn new() -> Result<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.
sourcepub fn assert(&mut self)
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.
sourcepub fn whitelist(&mut self, substring: &str) -> &mut TestRunner
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.
sourcepub fn whitelist_iter<I, S>(&mut self, substrings: I) -> &mut TestRunner
pub fn whitelist_iter<I, S>(&mut self, substrings: I) -> &mut TestRunner
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.
sourcepub fn blacklist(&mut self, substring: &str) -> &mut TestRunner
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.
sourcepub fn blacklist_iter<I, S>(&mut self, substrings: I) -> &mut TestRunner
pub fn blacklist_iter<I, S>(&mut self, substrings: I) -> &mut TestRunner
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.
sourcepub fn expand<S: AsRef<str>>(
&mut self,
additional_names: &[S],
predicate: impl FnMut(&RegexTest) -> bool + 'static,
) -> &mut TestRunner
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.
sourcepub fn test_iter<I, T>(
&mut self,
it: I,
compile: impl FnMut(&RegexTest, &[String]) -> Result<CompiledRegex>,
) -> &mut TestRunner
pub fn test_iter<I, T>( &mut self, it: I, compile: impl FnMut(&RegexTest, &[String]) -> Result<CompiledRegex>, ) -> &mut TestRunner
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.
sourcepub fn test(
&mut self,
test: &RegexTest,
compile: impl FnMut(&[String]) -> Result<CompiledRegex>,
) -> &mut TestRunner
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
.