Automatic Test Registration

Don't waste time writing test registration code. Life is too short for boilerplate!

Declare tests with the TEST directive and let Audition automatically register them for you! Filter which tests are run using glob patterns on the command-line.

TEST(account, deposit) {
    BankAccount *account = BankAccount_Open();

    // Successful bank deposit.
    ASSERT_TRUE(BankAccount_Deposit(account, 100));

    // Verify new account balance.
    ASSERT_EQ(BankAccount_GetBalance(account), 100);
}

TEST defines a test case named deposit and appends it to test suite account.

Function Mocking

Audition lets you mock functions without compiler flags or other external tools.

Mocking works like magic:

Select the C function you want to mock.
Use STUB to hardcode a return value or FAKE to redirect calls to an alternative implementation.

int add(int x, int y) {
    return x + y;
}

int fake_add(int x, int y) {
    return x * y; // do multiplication instead
}

TEST(math, add) {
    FAKE(add, fake_add);   // redirect add() to fake_add()
    int result = add(3,5); // returns 15 instead of 8
    // ...
}

FAKE redirects all function calls to add to fake_add.

Type-generic Assertions

Audition is the C unit testing framework of the future! It leverages generic selection (from C11) to implement type-generic assertion macros.

Review the complete list of available assertion macros here.

int   x = 1;
float y = 2.0f;
void *z = 0x0;

// Integers, floats, and pointers can be asserted using the
// same type-generic macros. Specialized generic macros are
// available for Unicode strings, memory blobs, and booleans.
ASSERT_EQ(x, 1);
ASSERT_EQ(y, 2.0f);
ASSERT_EQ(z, (void *)0x0);

Demonstrates type-generic assertion macros.

Sandbox Isolation

Test cases can be isolated in a separate address space known as the sandbox. The sandbox is useful for:

Testing intentional termination.
Testing POSIX signals.
Aborting a test case that exceeds a timeout.
Capturing standard output and error.
Simulating standard input.

TEST(program, greeting, sandbox=true) {
    // Simulate standard input and EOF.
    audit_write(stdin, "hello", 5);
    audit_close(stdin);

    // Call code that reads from standard input.
    char buf[10] = {0};
    fgets(buf, sizeof(buf), stdin);
    ASSERT_STR_EQ(buf, "hello");
}

Defines a test case that runs in the sandbox.

Detailed Error Reporting

Audition prints the C code where your assertion failed. This provides quick visual insight into what failed and where.

When comparing multi-line strings or binary blobs Audition prints a diff indicating where mismatches occurred.

1) bank_account.deposit (test_bank.c:11)
      Message: expected 'DEPOSIT' to equal 'balance'
       Assert: DEPOSIT = balance
        Found: 100 = 200
      |
    6 | TEST(bank_account, deposit)
    7 | {
    8 |     int balance, DEPOSIT = 100;
    9 |     BankAccount_Deposit(DEPOSIT * 2);
   10 |     balance = BankAccount_GetBalance();
   11 >     ASSERT_EQ(DEPOSIT, balance);
      |

Code snippet from a failing assertion.

---
+++
@@ -36,5 +36,5 @@
 By the grave and stern decorum of the countenance it wore, "Though thy
 crest be shorn and shaven, thou," I said, "art sure no craven,
-Ghastly grim and ancient Raven wandering from the Nightly shore-
+Ghastly grim and ancient Crow wandering from the Nightly shore-
 Tell me what thy lordly name is on the Night's Plutonian shore!"
-                                  Quoth the Raven, "Nevermore."
+                                  Quoth the Crow, "Nevermore."

Multi-line string diff output.

---
+++
@@ -0000,41 +0000,38 @@
-0000      | 41                            | A          |
 0001 0000 | DE AD BE EF BA AD F0 0D BA 6D | .........m |
 000B 000A | 00 00 00                      | ...        |
-000E      | 00                            | .          |
+     000D | BE AF C0                      | ...        |
 000F 0010 | DE                            | .          |
-0010      | AD                            | .          |

Binary diff output.

Easy Integration

Audition supports the following test result formats:

TAP
JUnit XML
Subunit

Choose any of these standardized formats to easily integrate Audition with your existing CI pipeline and dashboard.

Cross-platform

Audition is available for the following operating systems. For more details, review the compatibility table.

Windows 10+

macOS 13.2+

Ubuntu 22.04+

Fedora 40+