kitest/strategy/filter/
mod.rs

1//! Test filtering for kitest.
2//!
3//! A filter decides which tests from the input slice are included in the test run.
4//! Tests that do not match the filter are removed from the run entirely, and they
5//! cannot be pulled back in by later steps.
6//!
7//! This is different to ignoring: ignore is decided per test after filtering, and
8//! ignored tests still "exist" in the run (they can show up as ignored and they
9//! are still part of the formatter flow). Filtering removes tests before we even
10//! decide whether a test is ignored.
11//!
12//! In the default harness, filtering is mainly meant for the common workflow of
13//! picking a smaller set of tests to focus on (for example by name matching),
14//! rather than running the whole suite.
15//!
16//! Implement [`TestFilter`] to define a filter strategy for kitest.
17
18use crate::test::Test;
19
20mod no;
21pub use no::*;
22
23mod default;
24pub use default::*;
25
26/// The result of applying a [`TestFilter`].
27///
28/// This contains an iterator over the tests that are included in the run,
29/// as well as the number of tests that were filtered out.
30///
31/// The iterator is required to be an [`ExactSizeIterator`]. Knowing the
32/// number of remaining tests upfront allows other parts of the system
33/// to make better decisions, such as estimating a worker count in the
34/// runner or showing progress information in a formatter.
35#[derive(Debug)]
36pub struct FilteredTests<'t, I, Extra>
37where
38    I: ExactSizeIterator<Item = &'t Test<Extra>>,
39    Extra: 't,
40{
41    /// The tests that are included in the run.
42    pub tests: I,
43
44    /// The number of tests that were filtered out.
45    ///
46    /// This may be used by formatters to report how many tests did not
47    /// match the filter.
48    pub filtered_out: usize,
49}
50
51/// A strategy for selecting which tests are included in a test run.
52///
53/// A `TestFilter` is applied before any ignore logic or test execution.
54/// Tests that are filtered out are completely removed from the run and
55/// are never seen by later stages.
56///
57/// This trait is used by the test harness to reduce the set of tests
58/// it needs to work on.
59pub trait TestFilter<Extra> {
60    /// Filter the given slice of tests.
61    ///
62    /// The returned [`FilteredTests`] contains an iterator over the tests
63    /// that are included in the run, as well as the number of tests that
64    /// were filtered out.
65    ///
66    /// The iterator must yield references into the original `tests` slice
67    /// and must have an exact size.
68    fn filter<'t>(
69        &self,
70        tests: &'t [Test<Extra>],
71    ) -> FilteredTests<'t, impl ExactSizeIterator<Item = &'t Test<Extra>>, Extra>;
72}
kitest/strategy/filter/mod.rs

kitest/strategy/filter/
mod.rs
