Skip to main content

Suite

Struct Suite 

Source
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

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn suffixes<I, S>(self, values: I) -> Self
where I: IntoIterator<Item = S>, S: Into<String>,

Adds test-file suffixes in iteration order.

Each value follows Self::suffix() normalization.

Source

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.

Source

pub fn excludes<I, S>(self, values: I) -> Self
where I: IntoIterator<Item = S>, S: Into<String>,

Adds exact file or directory base names to the discovery exclusions.

Source

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.

Source

pub fn feature(self, value: impl Into<String>) -> Self

Makes one exact feature name available to boolean test directives.

Source

pub fn features<I, S>(self, values: I) -> Self
where I: IntoIterator<Item = S>, S: Into<String>,

Makes each supplied feature name available to boolean test directives.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn normalize_slashes(self, value: bool) -> Self

Controls whether path substitutions use forward slashes.

Source

pub fn limit_to_features<I, S>(self, values: I) -> Self
where I: IntoIterator<Item = S>, S: Into<String>,

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.

Source

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.

Source

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.

Source

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§

Source§

impl Debug for Suite

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for Suite

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

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> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.