Class Shell

• Defined in File Shell.hpp

Inheritance Relationships

Derived Types

• public mu::tiny::test::ExpectFailShell (Class ExpectFailShell)

• public mu::tiny::test::OrderedShell (Class OrderedShell)

• public mu::tiny::test::SkippedShell (Class SkippedShell)

Class Documentation

class Shell

Shell for a single test — tracks metadata and drives execution.

Each TEST() macro instantiates a Shell subclass and registers it with the Registry at static initialisation time. The test runner then calls run_one_test() for each registered shell.

Users interact with Shell primarily through the assertion macros (CHECK, CHECK_EQUAL, FAIL_TEST, etc.), which forward to the assert_* virtual methods. This design allows the testing framework’s own tests to substitute a mock shell and verify assertion behaviour.

The static methods control global runner state: the currently running test, the active Terminator, and crash-on-failure mode.

Subclassed by mu::tiny::test::ExpectFailShell, mu::tiny::test::OrderedShell, mu::tiny::test::SkippedShell

Public Functions

Shell(const char *group_name, const char *test_name, const char *file_name, int_least32_t line_number) noexcept

Construct a Shell with source-location metadata.

Called by the TEST() macro; users do not construct Shells directly.

Parameters:

• group_name – Name of the test group.

• test_name – Name of the individual test.

• file_name – Source file path (FILE).

• line_number – Source line number (LINE).

virtual ~Shell() = default

virtual Shell *add_test(Shell *test)

Append test to this shell’s linked list.

Returns:

test.

virtual Shell *get_next() const

Returns:

The next Shell in the registered list, or nullptr.

virtual size_t count_tests()

Returns:

Total number of test shells reachable from this node.

bool should_run(const Filter *group_filters, const Filter *name_filters) const

Decide whether this test should run given the active filters.

Parameters:

• group_filters – Filters applied to the group name (may be nullptr).

• name_filters – Filters applied to the test name (may be nullptr).

Returns:

true if the test should be executed.

const char *get_name() const

Returns:

The test name string.

const char *get_group() const

Returns:

The group name string.

virtual String get_formatted_name() const

Returns:

A formatted “group::name” string for display.

const char *get_file() const

Returns:

The source file path for this test.

int_least32_t get_line_number() const

Returns:

The source line number for this test.

virtual bool will_run() const

Returns:

true if the test will actually run (not ignored).

virtual bool has_failed() const

Returns:

true if the test has recorded at least one failure.

virtual bool is_ordered() const

Returns:

true if this is an ordered test.

virtual void assert_true(bool condition, const char *check_string, const char *condition_string, const char *text, const char *file_name, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

Macro backend: assert condition is true.

virtual void assert_cstr_equal(const char *expected, const char *actual, const char *text, const char *file_name, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

Macro backend: assert two C strings are equal (strcmp).

virtual void assert_cstr_n_equal(const char *expected, const char *actual, size_t length, const char *text, const char *file_name, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

Macro backend: assert first length bytes of two C strings match.

virtual void assert_cstr_contains(const char *expected, const char *actual, const char *text, const char *file_name, int_least32_t line_number)

Macro backend: assert actual contains the substring expected.

virtual void assert_intmax_equal(intmax_t expected, intmax_t actual, const char *text, const char *file_name, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

C-interface backend: assert two signed integer values are equal.

Both operands have been widened to long long (the same range as intmax_t on all supported platforms) by the caller.

virtual void assert_uintmax_equal(uintmax_t expected, uintmax_t actual, const char *text, const char *file_name, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

C-interface backend: assert two unsigned integer values are equal.

Both operands have been widened to unsigned long long (the same range as uintmax_t on all supported platforms) by the caller.

virtual void assert_pointers_equal(const void *expected, const void *actual, const char *text, const char *file_name, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

Macro backend: assert two pointers are equal.

template<typename T>
inline void assert_approx_equal(T expected, T actual, T threshold, const char *text, const char *file_name, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

Macro backend: assert two values are equal within threshold.

Template Parameters:

T – Numeric type; must have a mu::tiny::string_from() overload.

virtual void assert_equals(bool failed, const char *expected, const char *actual, const char *text, const char *file, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

Macro backend: generic equality failure with pre-formatted strings.

virtual void assert_equals(bool failed, String expected, String actual, const char *text, const char *file, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

Macro backend: generic equality failure with String arguments.

virtual void assert_binary_equal(const void *expected, const void *actual, size_t length, const char *text, const char *file_name, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

Macro backend: assert length bytes of two memory regions match.

virtual void assert_compare(bool comparison, const char *check_string, const char *comparison_string, const char *text, const char *file_name, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

Macro backend: assert a relational comparison holds.

virtual void fail(const char *text, const char *file_name, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

Unconditionally fail the test with a message.

Parameters:

• text – Human-readable failure reason.

• file_name – Source file (FILE).

• line_number – Source line (LINE).

• test_terminator – Controls how the test is aborted after the failure.

virtual void exit_test(const Terminator &test_terminator = get_current_test_terminator())

Exit the test body immediately without marking it as failed.

Parameters:

test_terminator – Controls how control leaves the test body.

virtual void skip_test(const char *text, const char *file_name, int_least32_t line_number, const Terminator &test_terminator = get_current_test_terminator())

Mark the test as skipped and exit the test body.

Parameters:

• text – Human-readable reason for skipping.

• file_name – Source file (FILE).

• line_number – Source line (LINE).

• test_terminator – Controls how control leaves the test body.

virtual void print_very_verbose(const char *text)

Print a message only when verbose output is active.

void set_file_name(const char *file_name)

Update the source file stored in this shell (used by ordered tests).

void set_line_number(int_least32_t line_number)

Update the source line stored in this shell.

void set_group_name(const char *group_name)

Update the group name stored in this shell.

void set_test_name(const char *test_name)

Update the test name stored in this shell.

virtual void set_run_skipped()

Mark this test to run even though it is an ignored test.

virtual class Test *create_test()

Allocate the Test object for this shell’s test group.

virtual void destroy_test(class Test *test)

Destroy a Test object previously returned by create_test().

virtual void run_one_test(Plugin *plugin, Result &result)

Run this test (create → setup → body → teardown → destroy).

virtual void run_one_test_in_current_process(Plugin *plugin, Result &result)

Run this test in the current process (no forking).

virtual void add_failure(const Failure &failure)

Record a test failure into the active Result.

virtual void add_test_property(const char *name, const char *value)

Attach a key/value property to this test.

Properties appear in JUnit XML output. Prefer the TEST_PROPERTY macro.

Parameters:

• name – Property name.

• value – Property value.

virtual String get_macro_name() const

Returns:

The macro keyword used in formatted output (e.g. “TEST”).

Public Static Functions

static Shell *get_current()

Returns:

The Shell currently executing, or nullptr between tests.

static const Terminator &get_current_test_terminator()

Returns:

The active test terminator (throws FailedException by default).

static const Terminator &get_current_test_terminator_without_exceptions()

Returns:

The active test terminator that never throws (used internally when exception support is disabled or inside CHECK_THROWS).

static void set_crash_on_fail()

Make the process crash (SIGABRT) instead of throwing on failure.

Useful when running under a debugger: the crash drops you straight into the failing assertion with the full call stack.

static void restore_default_test_terminator()

Restore the default (exception-based) Terminator.

static void set_rethrow_exceptions(bool rethrow_exceptions)

Control whether CHECK_THROWS re-throws unexpected exceptions.

When rethrow_exceptions is true, an exception of the wrong type caught inside CHECK_THROWS is re-thrown rather than recorded as a failure. This makes it easier to diagnose unexpected crashes during test development.

Parameters:

rethrow_exceptions – true to propagate unexpected exceptions.

static bool is_rethrowing_exceptions()

Returns:

true if unexpected exceptions are currently re-thrown.

static void count_check()

Increment the assertion-check count in the active Result.

static void crash()

Invoke the registered crash function (default: abort).

static void set_crash_method(void (*crashme)())

Replace the function called by crash().

Parameters:

crashme – Function to call when a crash is requested; must not return.

static void reset_crash_method()

Restore the default crash function.

Protected Functions

Shell() noexcept

Default constructor for use by subclasses.

Protected Static Functions

static Result *get_test_result()

Returns:

The Result for the current run.