CUnit

CUnit is a unit testing framework for C.

The basic framework is platform/version independent and should be portable to all platforms. CUnit provides various interfaces to the framework, some of which are platform dependent (for example, curses on Unix-like systems). Building other interfaces should be straightforward with the facilities provided in the framework.

CUnit is built as either a static or shared library which provides framework support when linked into user testing code. The framework complies with the conventional structure of test cases bundled into suites which are registered with the framework for running. See the documentation for more about the structure and use of the framework.

Tests can self-skip at runtime with CU_SKIP(reason) or CU_SKIP_IF(condition, reason). Skip reasons are copied by the framework and reported separately from inactive tests; if a test has already recorded a failure, it remains failed rather than skipped.

Note: the Windows-specific GUI interface is not yet written. It is still necessary to use either the automated, basic, or console interfaces to CUnit on Windows at this time.

Building the CUnit Library and Examples

All Platforms

Jam support has been removed. Use the GNU Autotools build on Unix-like platforms, or the Visual Studio project files on Windows.

Linux

The standard GNU build system should succeed in building and installing CUnit:

1. aclocal (if necessary)
2. autoconf (if necessary)
3. automake (if necessary)
4. chmod u+x configure (if necessary)
5. ./configure --prefix <installation-prefix>
6. make
7. make install

What is installed:

1. libcunit.a (library file)
2. CUnit header files
3. DTD and XSL files supporting XML output files in the share directory
4. Man pages in the relevant man directories under the installation path
5. The HTML users guide in the doc subdirectory of the installation path
6. Example and test programs in the share subdirectory of the install path

Testing

To build the internal CUnit self-tests from a git checkout, configure with --enable-test and then run make check:

1. ./configure --enable-test --prefix <installation-prefix>
2. make check

The internal test runner is built as CUnit/Sources/Test/test_cunit. You can also run it directly after make or make check:

• ./CUnit/Sources/Test/test_cunit

make check works because the internal runner is wired into Automake's usual TESTS mechanism in CUnit/Sources/Test/Makefile.am, and the runner exits non-zero if any internal assertions fail.

Windows

Jam support has been removed. A set of old VC6 project files is included which have been partially updated but not tested. If they do not work and you get them working, the project would be happy to include them in the CUnit distribution. A set of Visual Studio 2003/VC7 solution and project files has also been provided in the VC7 subdirectory. Similarly, a set of Visual Studio 2005/VC8 solution and project files is located in the VC8 subdirectory. The latter should work with all versions of VC 2005, including the Express edition.

Release Process

GitHub releases are created from version tags. The release workflow expects the VERSION file to contain the distribution version in the historical format, for example 2.1-3, and the Git tag to use the normalized form with dots, for example v2.1.3.

If the tag, VERSION, and packaging/msys2/PKGBUILD version fields do not all match, the release workflow fails before publishing any assets.

For ordinary branch and pull-request work, use the normal build workflows:

• CUnit Ubuntu Build builds from a git checkout on supported Ubuntu runners, runs the internal self-tests, installs the library, and reports coverage.
• CUnit MSYS2 Build builds from a git checkout on MSYS2 UCRT64, runs the internal self-tests, installs the library, and smoke-tests the installed pkgconf metadata.

These workflows are checkout builds. They do not validate release tarball packaging.

To dry-run the release build without publishing a GitHub release, manually run the CUnit Release workflow from GitHub Actions on the release branch. The optional release_tag input should match the normalized VERSION value, such as v2.1.3; if omitted, the workflow derives the expected tag from VERSION. From a feature branch, the equivalent GitHub CLI command is:

gh workflow run release.yml --ref your-feature-branch -f release_tag=v2.1.3

This runs the workflow on GitHub Actions using your-feature-branch as the source ref. The release_tag input is only validated against VERSION; it does not create a git tag or publish a GitHub release.

The release workflow builds one source tarball on Ubuntu with Automake make distcheck, then tests that same tarball on Ubuntu, Rocky 8, and MSYS2 UCRT64. The MSYS2 job builds its package from that tarball, installs the package, and runs the smoke test. A dry run uploads workflow artifacts only. The final GitHub release is created only for a pushed v* tag.

To publish a release:

1. Update VERSION and the packaging metadata.
2. Commit the release changes.
3. Create and push an annotated tag matching VERSION, such as v2.1.3.

The release workflow publishes both a source tarball and the MSYS2 UCRT64 .pkg.tar.zst package for the tagged commit. The source tarball is named cunit-<VERSION>.tar.gz, extracts into cunit-<VERSION>/, and is generated with Automake make distcheck, so it includes configure and the generated Makefile.in files. Building directly from a git checkout still requires ./bootstrap before ./configure.

Important Note: Changes to CUnit Structure and Interface

As of version 2.0, the interface functions used to interact with the CUnit framework have changed. The original interface did not attempt to protect user code from name clashes with public CUnit functions and variables. To minimize such name clashes, all CUnit public functions are now prefixed with CU_.

The old public names are deprecated as of version 2.0, but continue to be supported with conversion macros. In order to compile older code using the original interface, it is now necessary to compile with the macro -DUSE_DEPRECATED_CUNIT_NAMES defined. If there are any problems compiling older code, please file a bug report.

In addition, the DTD and XSL files for output from the automated test interface have been updated to support both old and new file structure. A List or Run file generated using the version 1.1 library should be valid under the version 2 DTDs and formatted correctly by the version 2 XSLs. This has not been extended to the Memory-Dump DTD and XSL files; memory dumps created using version 1.1 are ill-formed and incorrectly formatted using the version 2 DTD and XSL files.

Another exception to backward compatibility occurs if the user has directly manipulated the global variables in version 1.1. The original CUnit structure included global variables error_number and g_pTestRegistry which have been removed from the global namespace as of version 2.0. Any user code which directly accessed these variables will break. The variables must be retrieved using the accessor functions CU__get_error() and CU_get_registry().

Similarly, user code retrieving the active test registry and directly manipulating the uiNumberOfFailures or pResult members will break. These members have been moved to the TestRun.c part of the framework and are no longer available in the test registry as of version 2.0.

Another change in version 2.0 is the update of the framework terminology. What were termed "test groups" in the original structure are now called "suites", and "test cases" are now just "tests". This change was made to bring CUnit into conformance with standard testing terminology, and results in a change in the name of some functions, for example run_group_tests() is now CU_run_suite().