pub struct Suite { /* private fields */ }Expand description
A Lit suite configured and run from one Rust test entry point.
Builder methods consume and return the suite, so configuration can be kept
in one expression. Methods that accept collections add values; scalar
methods replace the corresponding setting. Call Self::run_from_args()
from a harness-free Cargo integration test.
Implementations§
Source§impl Suite
impl Suite
Sourcepub fn new(root: impl Into<PathBuf>) -> Self
pub fn new(root: impl Into<PathBuf>) -> Self
Creates a suite whose source and execution roots start at root.
Discovery is recursive. Add at least one suffix with Self::suffix();
no suffixes are enabled initially. Set Self::exec_root() to keep
generated Output directories outside the source tree. A suite with no
matching files fails when it runs.
A relative root is resolved against the process working directory when this method is called.
§Panics
Panics if root is relative and the process working directory is not
available, or if a process environment variable is not valid Unicode.
Sourcepub fn with_root(self, root: impl Into<PathBuf>) -> Self
pub fn with_root(self, root: impl Into<PathBuf>) -> Self
Replaces the source and discovery root.
This clears a prior Self::source_root() override and retains the
execution root and all other settings. A relative root is resolved
against the process working directory when this method is called.
§Panics
Panics if root is relative and the process working directory is not
available.
Sourcepub fn tool(self, name: impl Into<String>, path: impl Into<PathBuf>) -> Self
pub fn tool(self, name: impl Into<String>, path: impl Into<PathBuf>) -> Self
Registers an executable under an exact RUN: command name.
A later registration replaces the path for the same name. Registered
tools take precedence over PATH; the embedded FileCheck command takes
precedence over a tool registered with that name. A relative path is
resolved against the process working directory when this method is
called.
§Panics
Panics if path is relative and the process working directory is not
available.
Sourcepub fn suffix(self, suffix: impl Into<String>) -> Self
pub fn suffix(self, suffix: impl Into<String>) -> Self
Adds one suffix used to select test files.
A leading dot is optional. An empty suffix is ignored.
Sourcepub fn suffixes<I, S>(self, values: I) -> Self
pub fn suffixes<I, S>(self, values: I) -> Self
Adds test-file suffixes in iteration order.
Each value follows Self::suffix() normalization.
Sourcepub fn exclude(self, value: impl Into<String>) -> Self
pub fn exclude(self, value: impl Into<String>) -> Self
Excludes an exact file or directory base name from discovery.
Inputs, Output, .git, and .svn are excluded independently of
this setting.
Sourcepub fn excludes<I, S>(self, values: I) -> Self
pub fn excludes<I, S>(self, values: I) -> Self
Adds exact file or directory base names to the discovery exclusions.
Sourcepub fn substitution(
self,
pattern: impl Into<String>,
value: impl Into<String>,
) -> Self
pub fn substitution( self, pattern: impl Into<String>, value: impl Into<String>, ) -> Self
Adds a regular-expression substitution for RUN: directives.
Substitutions run in insertion order before built-in path forms. The
replacement is literal text, so $ does not expand capture groups. An
invalid pattern makes each affected test UNRESOLVED during preparation.
Sourcepub fn feature(self, value: impl Into<String>) -> Self
pub fn feature(self, value: impl Into<String>) -> Self
Makes one exact feature name available to boolean test directives.
Sourcepub fn features<I, S>(self, values: I) -> Self
pub fn features<I, S>(self, values: I) -> Self
Makes each supplied feature name available to boolean test directives.
Sourcepub fn env(self, key: impl Into<String>, value: impl Into<String>) -> Self
pub fn env(self, key: impl Into<String>, value: impl Into<String>) -> Self
Sets one variable in the environment snapshot passed to test commands.
The initial snapshot contains the Unicode variables visible when
Self::new() created the suite.
Sourcepub fn source_root(self, root: impl Into<PathBuf>) -> Self
pub fn source_root(self, root: impl Into<PathBuf>) -> Self
Sets the source root used for discovery and source-path substitutions.
A relative root is resolved against the process working directory when this method is called.
§Panics
Panics if the root is relative and the process working directory is not available.
Sourcepub fn exec_root(self, root: impl Into<PathBuf>) -> Self
pub fn exec_root(self, root: impl Into<PathBuf>) -> Self
Sets the root used for working directories and temporary files.
The runner creates the required directories when a test executes. A relative root is resolved against the process working directory when this method is called.
§Panics
Panics if the root is relative and the process working directory is not available.
Sourcepub fn recursive_expansion_limit(self, value: usize) -> Self
pub fn recursive_expansion_limit(self, value: usize) -> Self
Requires substitutions to stabilize within value additional passes.
The runner always applies the initial substitution pass.
Sourcepub fn max_individual_test_time(self, seconds: u64) -> Self
pub fn max_individual_test_time(self, seconds: u64) -> Self
Sets the time limit for one complete test attempt, in seconds.
The same deadline covers all RUN: lines in the attempt. Zero disables
the limit. The runner stops child processes at the deadline but cannot
interrupt an embedded command while it runs.
Sourcepub fn no_execute(self, value: bool) -> Self
pub fn no_execute(self, value: bool) -> Self
Controls whether preparation succeeds without executing RUN: commands.
When enabled, the runner reads directives, evaluates feature conditions,
and applies substitutions. A test that passes preparation receives
PASS, or XPASS when an XFAIL: condition is active, with the rendered
commands. The runner does not parse or execute those commands.
Sourcepub fn with_pipefail(self, value: bool) -> Self
pub fn with_pipefail(self, value: bool) -> Self
Controls whether a non-final failed stage fails its pipeline.
Pipefail is enabled when a suite is created.
Sourcepub fn normalize_slashes(self, value: bool) -> Self
pub fn normalize_slashes(self, value: bool) -> Self
Controls whether path substitutions use forward slashes.
Sourcepub fn limit_to_features<I, S>(self, values: I) -> Self
pub fn limit_to_features<I, S>(self, values: I) -> Self
Restricts execution to tests that depend on at least one listed feature.
A selected test must satisfy all of its REQUIRES: expressions, and at
least one expression must become false when the listed features are
removed. Other tests receive UNSUPPORTED.
Sourcepub fn test_retry_attempts(self, attempts: usize) -> Self
pub fn test_retry_attempts(self, attempts: usize) -> Self
Sets the number of retries after an initial FAIL result.
TIMEOUT and UNRESOLVED results are not retried. An
ALLOW_RETRIES: directive in a test replaces this setting.
Sourcepub fn run(self, args: Arguments) -> Conclusion
pub fn run(self, args: Arguments) -> Conclusion
Discovers the suite and runs it through libtest-mimic.
A discovery error or zero matching files produces one failing entry
named litnik :: discovery. UNSUPPORTED, SKIPPED, and EXCLUDED
results become ignored harness entries. XFAIL and FLAKYPASS become
successful entries because libtest-mimic has no custom success status.
Use formats::run_shtest() when the exact TestResult::code is
required.
The returned Conclusion does not terminate the process.
§Blocking
This method performs synchronous filesystem access and waits for child processes. Independent tests can run in parallel through the harness.
Sourcepub fn run_from_args(self) -> !
pub fn run_from_args(self) -> !
Parses the process arguments, runs the suite, and exits with its status.
This is the terminal call for a harness-free Cargo test target.
Trait Implementations§
Auto Trait Implementations§
impl Freeze for Suite
impl RefUnwindSafe for Suite
impl Send for Suite
impl Sync for Suite
impl Unpin for Suite
impl UnsafeUnpin for Suite
impl UnwindSafe for Suite
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more