Welcome to the Erbsland UnitTest Documentation!

Erbsland Unit Test is a standalone unit testing framework tailored for testing libraries and applications with simplicity and efficiency in mind. Designed to boost developer productivity, it features minimal dependencies—requiring only C++, CMake, and Python—and is compatible with any compiler supporting c++20 or newer.

Minimal dependencies:

Requires only C++, CMake, and Python.

Broad compatibility:

Supports any compiler adhering to C++20 or newer.

Get Started →

Familiar with the framework? Dive into the specifics with chapters on:

• Structure and Naming

• The UnitTest Class

• CMake Integration

• Macros for Unittests

• Command Line Options for the Unit Test Executable

• Advanced Usages

• GitHub Integration

Contents at a Glance

• Getting Started
  • The Project Structure
    • Organizing Your Project for Success
    • Create the Structure
  • The CMake Configuration
    • Configuring the Root Project CMake File
    • Setting Up the Unit Test CMake File
  • Write the Test!
    • Creating the main.cpp File
    • Creating Your First Unit Test
    • Adding the Test Suite to the CMake Configuration
  • Build the Test!
    • Generate Build Files with CMake
    • Compile the Unit Test
  • Run the Test!
    • Run the Unit Test
    • Get Command Line Help
    • List All Tests, Tags, and Targets
    • Filtering Tests
  • What’s Next?
    • Explore the Full Example
    • Dive Deeper Into the Framework
• Structure and Naming
  • Structure for Separate Tests
  • Structure for Integrated Tests
    • Optional Test Inclusion via CMake
  • Organizing your Tests
  • Naming of Classes and Methods
  • Split Declaration and Implementation
  • Helper Functions
  • Instance Variables
• The UnitTest Class
  • The additionalErrorMessages() Function
  • The setUp() and tearDown() Methods
  • The runWithContext() Method
  • The consoleWriteLine() Method
  • The unitTestExecutablePath() Method
• CMake Integration
  • Configuring the Root CMake File
  • Configuring the Unit Test Project
  • Utilizing the erbsland_unittest Function
    • How to Use
    • About Test Data Dependencies
    • Example
• Macros for Unittests
  • Quick Overview
    • Macros for Tests
    • Comparison Macros
    • Macros for Meta Data
    • Helper Macros
  • The REQUIRE(expression) Macro
  • The REQUIRE_FALSE(expression) Macro
  • The REQUIRE_THROWS(expression) Macro
  • The REQUIRE_THROWS_AS(exception class, expression) Macro
  • The REQUIRE_NOTHROW(expression) Macro
  • Macros for Value Comparison
    • Comparison Macros
    • Example Error Message
    • Custom Formatting with std::format
  • The CHECK_... Macros
  • The WITH_CONTEXT(expression) Macro
  • Add Tags with TAGS(...)
  • Add Targets with TESTED_TARGETS(...)
  • Skip Tests by Default with SKIP_BY_DEFAULT()
  • Combine TAGS(...), TESTED_TARGETS(...) and SKIP_BY_DEFAULT()
  • The Macro SOURCE_LOCATION()
  • The Macro ERBSLAND_UNITTEST_MAIN()
• Command Line Options for the Unit Test Executable
• Advanced Usages
  • Sharing Functionalities with a Common Base Class
  • Organizing Your Tests with Labels
    • Adding Tags to Test Classes and Functions
    • Adding Targets to Track Tested Functions
    • Example: Marking Long-Running Tests
• GitHub Integration
  • Verify CTest Activation
  • Create the Workflow File
  • Step-by-Step Explanation
    • Workflow Trigger
    • Job Definition
    • Checkout the Repository
    • Cache the Build
    • Install Dependencies
    • Configure the Build
    • Build the Project
    • Run the Tests
  • Final Outcome
• Bug Reports and Feature Requests
• Goals
  • Dependency-Free
  • User-Friendly
  • Minimalistic
  • Modern
  • Secure
  • Scalable
• Requirements
  • Code-Level Requirements
  • Build and Metadata System Requirements
• License
• Reference
  • Classes
    • erbsland::unittest::UnitTest
  • Macros
    • REQUIRE
    • REQUIRE_FALSE
    • REQUIRE_THROWS
    • REQUIRE_THROWS_AS
    • REQUIRE_NOTHROW
    • REQUIRE_EQUAL
    • REQUIRE_NOT_EQUAL
    • REQUIRE_LESS
    • REQUIRE_LESS_EQUAL
    • REQUIRE_GREATER
    • REQUIRE_GREATER_EQUAL
    • CHECK
    • CHECK_FALSE
    • CHECK_THROWS
    • CHECK_THROWS_AS
    • CHECK_NOTHROW
    • CHECK_EQUAL
    • CHECK_NOT_EQUAL
    • CHECK_LESS
    • CHECK_LESS_EQUAL
    • CHECK_GREATER
    • CHECK_GREATER_EQUAL
    • WITH_CONTEXT
    • TAGS
    • TESTED_TARGETS
    • SKIP_BY_DEFAULT
    • SOURCE_LOCATION
    • UNITTEST_SUBCLASS
    • ERBSLAND_UNITTEST_MAIN
  • Namespaces
    • erbsland
    • erbsland::unittest
    • Shortcuts
    • Prevent or Redefine the Shortcuts

Indices and Tables

• Index

• Module Index

• Search Page