Suitcase

The structured test toolkit. A lightweight sync Rust library for named cases, optional setup / teardown at suite scope and before_each / after_each around each case. Build case lists with cases!; use test_suite! to emit a single #[test] that runs all cases sequentially with formatted output.

Heavy development: The API is still evolving. Expect breaking changes between releases until a stable 1.0; pin an exact version (or git revision) in Cargo.toml if you need upgrades to be predictable.

Install · Usage · CLI · Assertions · Mocking · Examples · AI-assisted changes · Docs (after publish; cargo doc --open locally)

• Sync runner — run orchestrates hooks and case bodies; integrate async I/O with something like tokio::runtime::Handle::block_on in hooks or cases.
• Sequential execution — test_suite! emits one #[test] that runs all cases in slice order. Cases that depend on earlier state (setup → mutate → assert) always execute correctly.
• Formatted output — Each case prints ▶ name, then ✓ name (Xms) or ✗ name (Xms). All cases run even if one fails; the first panic is re-raised after completion.
• Hooks as optional fns — HookFns holds Option<fn(&mut S)> per lifecycle slot; use [None] to skip.
• CLI — suitecase test runs suitecase test and renders a formatted summary with pass/fail counts, per-case timing, and failure details.
• Assertions — suitecase::assert provides testify/assert-style helpers (equal, contains, assert_ok, …) that panic on failure with clear messages (#[track_caller] where applicable).
• Mocking — suitecase::mock provides testify/mock-style expectations and call recording (Mock, mock_args!). Use suitecase::mock_args at the crate root (same macro).

Install

Add suitecase to your Cargo.toml (no required dependencies beyond std):

[dependencies]
suitecase = "0.1"

Install the CLI:

cargo install suitecase

CLI

Run tests with formatted suitecase output:

suitecase test --lib
suitecase test --example quickstart
suitecase test --example sqlx_sqlite
suitecase test --lib -- shared_state    # filter by test name

Output:

Suitecase Summary
────────────────────────────────────────────────
  ✓ test_inc (0ms)
  ✓ test_inc_verify (0ms)
  ✓ test_double (0ms)
  ...
────────────────────────────────────────────────
  PASSED  12 passed, 0 failed  (total: 0ms)

On failure, a FAILURES section shows the panicked case name, duration, file location, and assertion message.

Usage

Quickstart

Put this in tests/suite.rs or #[cfg(test)] mod tests { ... }. The example is suitecase test --example quickstart — one test line that runs every case in order on one suite.

use suitecase::{cases, run, Case, HookFns, RunConfig};

#[derive(Default)]
struct Counter {
    n: i32,
}

impl Counter {
    fn test_inc(&mut self) {
        self.n += 1;
    }
    fn test_inc_verify(&mut self) {
        assert_eq!(self.n, 1);
    }
}

static MY_CASES: &[Case<Counter>] = cases![Counter, s =>
    test_inc => { s.test_inc(); },
    test_inc_verify => { s.test_inc_verify(); },
];

static MY_HOOKS: HookFns<Counter> = HookFns {
    setup_suite: None,
    teardown_suite: None,
    before_each: None,
    after_each: None,
};

#[test]
fn quickstart() {
    let mut suite = Counter::default();
    run(&mut suite, MY_CASES, RunConfig::all(), &MY_HOOKS);
}

Run: suitecase test.

Hooks

Pass HookFns as the last argument to run. Each field is Option<fn(&mut S)> — [Some(...)] or [None] / [HookFns::default()].

Sequential test suite (test_suite!)

test_suite! emits a single #[test] that runs all cases sequentially in slice order. Each case prints ▶ name before execution and ✓ name (Xms) or ✗ name (Xms) after. All cases run even if one fails — the first panic is re-raised after all cases complete.

use suitecase::{test_suite, HookFns};

#[derive(Default)]
struct Counter { n: i32 }

test_suite!(
    Counter,
    MY_SHARED_SUITE,
    quickstart_test_run,
    Counter::default(),
    HookFns::default(),
    s =>
    test_inc => { s.n += 1; },
    test_inc_verify => { assert_eq!(s.n, 1); },
);

Run: suitecase test or suitecase test.

Assertions (assert)

Import helpers from suitecase::assert inside #[test] functions, suite case bodies, or anywhere you want a named check that fails by panicking with a readable message.

use suitecase::assert::{assert_ok, contains_str, equal};

let n = assert_ok(Ok::<_, &str>(42));
equal(&n, &42);
contains_str("hello world", "world");

See the module docs for the full flat list (collections, errors, floats, options/results, ordering, panics, pointers, time, …).

Mocking (mock)

suitecase::mock is for test doubles: register expectations on a Mock, forward calls from your stub with method_called and mock_args!, then verify with assert_expectations and a small TestingT implementation.

use suitecase::mock::{eq, Mock, TestingT};

struct NoopT;
impl TestingT for NoopT {
    fn errorf(&self, _: &str) {}
    fn fail_now(&self) {}
}

let m = Mock::new();
m.on("greet", vec![eq("Ada".to_string())])
    .returning(|| vec![Box::new("Hello, Ada".to_string())])
    .finish();

let out = m.method_called("greet", suitecase::mock_args!("Ada".to_string()));
assert_eq!(out.string(0), "Hello, Ada");
assert!(m.assert_expectations(&NoopT));

Unexpected calls panic from method_called (see rustdoc). Matchers include eq, anything, anything_of_type, matched_by.

Examples

The sqlx example uses sqlx + tokio, embedded migrations in setup_suite, and cases! blocks that call helper functions, plus test_suite!.

[dependencies]
suitecase = "0.1"
sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite", "migrate"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

More documentation

• AI_USAGE.md — using LLMs to draft changes is allowed; you must understand the patch, justify it in review, and avoid unnecessary complexity (see file).
• cargo doc --open — cases! and test_suite! include declaration / description / examples.
• Crate root and suite describe how run selects cases and orders hooks.
• assert — panicking assertion helpers (submodules per domain; flat re-exports at the module root).
• mock — Mock, matchers, Arguments, mock_args!.