After conversion to clar of the first batch of test files in the blog post: Prioritizing-test-files, I embarked on the next batch of test files listed in the Next Steps section of the blog post: Modifying-expectations, both of which have now been merged into the Git’s project master branch. In this blog, I want to reflect on the process and my experience converting the test second batch of test files.

Before taking on the second batch of test conversions to use the clar testing framework, I underestimated the time and effort it would take to convert. This problem will be discussed further in the Difficulties section of this blog.

Pre-conversion steps

Similarly to the previous batch of test conversions, the initial stage involves learning and understanding how the following test files work;

  • t-example-decorate.c: This verifies the decoration API by ensuring that objects can be correctly added with or without decorations. It first tests that newly added objects return NULL as their previous decoration and that decorations can be assigned properly. Then, it checks re-adding behavior, ensuring that if an object is re-added, the old decoration is correctly returned instead of being silently overwritten.

    The lookup functionality is also tested to confirm that lookup_decoration() retrieves the correct decoration for objects that were added while returning NULL for those that were never decorated. Additionally, the suite verifies that all decorated objects can be iterated over, ensuring that looping through decorations correctly accounts for all stored entries.

  • t-strcmp-offset.c: Checks the correctness of strcmp_offset(), a function that compares two strings while also identifying the position of the first differing character. The check_strcmp_offset() function runs the comparison, normalizes the return value to -1, 0, or 1 (to handle variations in C runtime behavior), and checks if both the comparison result and the offset match expectations.

    The test cases cover various scenarios, such as identical strings returning an offset equal to their length, completely different strings differing from the first character, and partial matches where the first differing character is identified correctly.

  • t-hashmap.c: This test file verifies the functionality of a hashmap implementation by defining and testing a test_entry structure that stores key-value pairs. The keys and values are stored as null-terminated strings within a flexible array member. The hashmap supports case-sensitive and case-insensitive comparisons, determined by a flag passed during initialization.

    The file includes functions for allocating and retrieving entries, adding and replacing key-value pairs, removing entries, and iterating over the hashmap. The t_replace function tests whether inserting a duplicate key replaces the old value while verifying correct behavior under different case settings. The t_get function ensures that retrieving values by key returns expected results, even when case insensitivity is enabled. The t_add function tests adding multiple entries and verifies that all key-value pairs are correctly stored and retrievable.

    The t_remove function ensures that removing entries works as expected and verifies that non-existent keys are handled gracefully. The t_iterate function tests the hashmap’s ability to iterate over stored entries, ensuring that all expected key-value pairs are visited without duplication. The t_alloc function checks memory allocation and hashmap resizing behavior as entries are inserted and removed.

  • t-strbuf.c: This test file verifies the functionality of the strbuf structure by defining and executing tests for various operations. The setup and setup_populated functions serve as wrappers that initialize an empty or pre-filled strbuf, respectively, before passing it to test functions.

    The assert_sane_strbuf function ensures that a strbuf is in a valid state by checking its buffer’s null-termination, memory allocation, and initialization behavior. The t_static_init test verifies that statically initialized strbuf instances have zero length, zero allocation, and a null-terminated buffer. The t_dynamic_init test checks dynamic initialization with a predefined allocation size and ensures that the buffer is correctly allocated and null-terminated.

    The t_addch function tests strbuf_addch, which appends a single character to the buffer. It verifies that the buffer length increases appropriately and remains null-terminated. The t_addstr function tests strbuf_addstr, ensuring that adding a string correctly appends it to the buffer while maintaining memory safety and termination.

Conversion Phase

Converting the test code to use the clar testing framework involved replacing the homegrown assertions with clar’s assertions. The process also includes refactoring the test structure to conform with clar’s recommended structure. All unit test files prefixed with t- were renamed to begin with u- to conform with our standard practice to differentiate homegrown unit tests from clar tests. All converted tests were also wired to our Makefile and Meson build files. Specific details about individual test file conversion will be discussed below;

  • u-hashmap.c: The hashmap test file was improved with better struct organization, optimized test cases, and case-insensitive comparisons.

    The main modifications replaced older test assertions like check_pointer_eq, check_int, and check_str with cl_assert equivalents. These changes improved consistency with the Clar testing framework by using cl_assert, cl_assert_equal_p for pointer comparisons, cl_assert_equal_s for string comparisons, and cl_assert_equal_i for integer checks. Additionally, redundant conditional checks and test messages were removed, simplifying the test structure while maintaining correctness.

    Lastly, the function t_intern was renamed test_hashmap__intern, aligning it with the standardized naming convention for tests run in place.

  • u-example-decorate.c: The test structure was refactored by replacing the single cmd_main function with separate test functions such as test_example_decorate__initialize, test_example_decorate__cleanup, test_example_decorate__add, and others.

    test_example_decorate__initialize() was added to set up object IDs and ensure a consistent test state. test_example_decorate__cleanup() was introduced to clear decorations after each test, preventing interference. The test file was adapted to the Clar framework, replacing assertions and eliminating dependencies on previous tests.

    Assertions were updated from the custom check() macro to Clar’s cl_assert_* macros. Pointer comparisons were changed to use cl_assert_equal_p, while integer comparisons used cl_assert_equal_i, improving consistency.

    The test_example_decorate__loop function was modified to iterate through decorations and assert the correct count of noticed objects. Additionally, test_example_decorate__cleanup was introduced to clear decorations at the end of tests, ensuring test isolation.

  • u-strbuf.c: Assertions previously using the check_uint, check_char, and check_str macros were replaced with Clar’s cl_assert_* macros. This change ensured consistency with the framework and improved readability. Pointer comparisons were also changed to cl_assert, while integer and string comparisons were updated accordingly.

    The assert_sane_strbuf function was modified to return void instead of int, eliminating unnecessary return values. The function’s logic was adjusted to improve clarity, ensuring that allocated buffers met the expected conditions.

    The test functions were refactored to follow the naming convention test_strbuf__. The monolithic `cmd_main` function was removed, and individual test functions were created for `static_init`, `dynamic_init`, `add_single_char`, `add_empty_char`, `add_append_char`, `add_single_str`, and `add_append_str`. This improved modularity and maintainability.

  • u-strcmp-offset: Assertions using check_int and check_uint were replaced with Clar’s cl_assert_equal_i for integer comparisons. This change ensured consistency with the framework and improved readability. The TEST_STRCMP_OFFSET macro was removed, and individual test functions were introduced. Instead of running all checks within cmd_main.

    Separate functions were created for different cases: test_strcmp_offset__empty (introduced to verify check_strcmp_offset() behavior when both input strings are empty.), test_strcmp_offset__equal, test_strcmp_offset__different, test_strcmp_offset__mismatch, and test_strcmp_offset__different_length. This modular approach improved test organization and maintainability.

Difficulties

Coming off the dopamine and adrenaline rush associated with the successful conversions of the first batch of the homegrown unit tests to use the clar testing framework. I grossly underestimated the effort and time it would take to convert the next batch of test files.

I spent most time stuck on t-strbuf.c test file. A segmentation fault occurred when I modified the check for an empty buffer. The issue came from removing the explicit return for cases where buf->len == 0 && buf->alloc == 0. Without this safeguard, the function proceeded to the next assertion, cl_asser(buf->len < buf->alloc), which attempted to compare buf->len and buf->alloc, potentially accessing uninitialized memory or violating expected conditions.

Next Steps

Having completed the batch of test files, my focus is now on converting the test files listed below;

  • t-oid-array.c
  • t-oidmap.c
  • t-oidtree.c
  • t-trailer.c

I’ll be sure to update you all, stay tuned :)