Crate extel

Extel - Extended Testing Library

Extel is a testing library that intends to help create scalable test suites with stateless tests. Extel’s primary purpose is to make writing tests fast, easy, and performant. A common use case for Extel is when writing integration tests for external binaries/executables. Extel comes with some macros for creating and parsing command results to streamline the process of creating and running CLI commands.

Think of Extel like a scripting language for tests. There’s no need for importing a set of wacky modules, or writing weird redirections in a shell language to capture stdout. Instead, you can use Extel to save the output or status results of the commands you want to run, and then chose where your test output goes, too!

Usage

Extel is intended to function on zero argument or single argument functions (the former being called single tests and the latter parameterized tests). After creating your test function, you can register it using the init_test_suite macro. This will scaffold a struct containing pointers to the functions passed in. Calling the run function on the generated struct will immediately go through all tests and collect the results into a vector for the user to parse through if they so wish.

Note that all Extel test functions expect an ExtelResult in its return. Using another type will cause the macros generating the test suite to fail, or will return some weird errors while using the parameters proc macro.

use extel::prelude::*;
use extel_parameterized::parameters;

fn single_test() -> ExtelResult {
    let mut my_cmd = cmd!("echo -n \"hello world\"");
    let output = my_cmd.output()?;
    let string_output = String::from_utf8(output.stdout)?;

    extel_assert!(
        string_output == *"hello world",
        "expected 'hello world', got '{}'",
        string_output
    )
}

#[parameters(1, 2, -2, 4)]
fn param_test(x: i32) -> ExtelResult {
    extel_assert!(x >= 0, "{} < 0", x)
}

fn main() {
    init_test_suite!(ExtelDemo, single_test, param_test);
    ExtelDemo::run(TestConfig::default());
}

Modules

errors

Extel errors built using thiserror.

prelude

Macros

cmd

Constructs a Command as if receiving the command directly from the CLI. Arguments wrapped in single or double quotes are treated as single arguments, allowing multiple tokens to be passed as a single argument to a command.

err

A macro to create an Error::TestFailed.

extel_assert

Assert if a given condition is true/false. If the condition is true, call the pass macro, else call the fail macro.

fail

A macro to create a failing ExtelResult.

init_test_suite

The test suite initializer that constructs test suits based on the provided name (first parameter) and the provided functions (the comma-delimited list afterwards). Every function that is provided is expected only to return type ExtelResult, and should have no parameters.

pass

A macro to create a passing ExtelResult.

Structs

Test

A test instance that contains the test name and the test function that will be run.

TestConfig

A test configuration type that determines what features will be enabled on the tests.

TestResult

A test result item that contains the name of the test and a result value. The value can either be a success or a failure. If a failure, there will be an underlying message as well to explain the context of the failure.

Enums

OutputDest

The output method for logging test results.

TestStatus

A test result variant that helps distinguish between standard, or single, tests and parameterized tests. Both the Single and Parameterized variants contain one or more ExtelResult.

Traits

GenericTestResult

Represents a generic test result. The test result can be extracted into a TestStatus to determine if the result came from a parameterized or single test.

RunnableTestSet

A test set that produces a list of test results.

Functions

output_test_result

Output the test results to the desired stream. This function is public only to give availability to the test initializer. If you wish to generate test output, consider RunnableTestSet::run.

Type Aliases

ExtelResult

The expected return type of extel test functions. This type is represented as a result type to allow error propogation.

Attribute Macros

parameters

Convert a single argument function into a parameterized function. The expected function signature is a single argument function (can be any type) that returns an ExtelResult.