# Playbook: add a unit test file

Recipe for a new `tests/unittests/test_<topic>.c` + `.h` pair.

## 1. Create the header

`tests/unittests/test_<topic>.h`:

```c
#ifndef TEST_<TOPIC>_H
#define TEST_<TOPIC>_H

void test_<topic>_<scenario_1>(void** state);
void test_<topic>_<scenario_2>(void** state);

#endif
```

One declaration per test function. Headers exist solely so `unittests.c` can
include them and reference each function symbol.

## 2. Create the source

`tests/unittests/test_<topic>.c`:

```c
#include "config.h"
#include "prof_cmocka.h"

#include <stdarg.h>
#include <stddef.h>
#include <setjmp.h>
#include <cmocka.h>

#include "test_<topic>.h"
// ... includes for the unit under test and any types it needs ...

void
test_<topic>_<scenario_1>(void** state)
{
    // Arrange — `will_return`, `expect_string`, etc.
    // Act    — call the unit
    // Assert — `assert_*`
}
```

## 3. Register in `unittests.c`

```c
#include "test_<topic>.h"

// inside the tests[] array passed to cmocka_run_group_tests:
cmocka_unit_test(test_<topic>_<scenario_1>),
cmocka_unit_test(test_<topic>_<scenario_2>),
```

If multiple tests share fixture, add a setup / teardown pair and use
`cmocka_unit_test_setup_teardown` (or define a per-topic macro near the top
of `unittests.c`, like `muc_unit_test`).

## 4. Stubs

For each external function the unit calls, ensure a stub exists in the
matching `tests/unittests/<module>/stub_*.c`. Three flavours:

- **Pass-through** — no observation needed.
- **`mock()` / `will_return`** — test injects return values.
- **`check_expected()` / `expect_*`** — test asserts arguments.

See `testing/stubs.md`.

## 5. Wire into Make

`tests/unittests/Makefile.am` (or the active wiring file): add
`test_<topic>.c` to the `unittests_SOURCES` (or equivalent) list. Same for
any new stub file.

## 6. Build & run

Inside Docker:

```sh
./autogen.sh && ./configure && make -j$(nproc) check
```

Diagnose failures via `tests/unittests/unittests.log` and the cmocka stderr
output.

## 7. Conventions

- Test functions: `test_<topic>_<scenario>` — never `test_topic1`,
  `test_topic2`. Names should describe the scenario.
- One assertion focus per test (multiple `assert_*` calls are fine; multiple
  *unrelated* assertions are not).
- Don't reuse stubs across topic suites unless the call truly is uniform —
  diverging behaviour is a strong sign you want a dedicated stub.
- No I/O in unit tests. Filesystem, network, ncurses are all stubbed.