# How Unit Tests and Integration Tests Are Organized in the codebase-memory-mcp Repository

> Discover how unit and integration tests are organized in the codebase-memory-mcp repository. Explore the combined testing approach using MiniTest, shell scripts, and Python.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-14

---

**The DeusData/codebase-memory-mcp repository consolidates all testing logic in a single top-level `tests/` directory that uses a custom MiniTest framework for C unit tests, supplemented by shell scripts and Python harnesses for integration and stress testing.**

The project adopts a flat, centralized approach to software verification. Instead of scattering tests throughout the source tree, all unit tests, integration tests, and platform-specific harnesses live under one umbrella directory. This structure leverages a lightweight C testing framework to provide assertion macros and test registration while relying on external scripts for complex multi-process scenarios.

## Test Directory Structure

The repository organizes verification code into logical categories within the `tests/` folder. Each file follows a strict naming convention that signals its purpose to the build system.

### Unit Tests in `tests/*.c`

Individual C source files in the `tests/` directory contain **unit tests** that exercise specific modules or data structures. Files such as [`tests/test_str_util.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_str_util.c), [`tests/test_store_nodes.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_store_nodes.c), and [`tests/test_sqlite_writer.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_sqlite_writer.c) each isolate a single component and verify its behavior through direct function calls. These files compile into standalone binaries that return pass or fail status.

### Integration Tests

The file [`tests/test_integration.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_integration.c) serves as the primary **integration test** entry point. It spins up the full MCP (Model Context Protocol) pipeline and validates end-to-end behavior by exercising multiple modules in concert. Unlike unit tests that mock dependencies, this file tests the actual interaction between the storage layer, protocol handlers, and memory management components.

### Shell and Python Harnesses

For scenarios requiring multi-process orchestration or platform-specific validation, the repository includes shell scripts and Python utilities:

- [`tests/test_security_strings_allowlist.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_security_strings_allowlist.sh) performs security-focused integration checks against string handling
- [`tests/test_mcp_rapid_init.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_mcp_rapid_init.py) drives rapid initialization and stress testing scenarios
- `scripts/test-windows.ps1` handles Windows-specific execution paths

These harnesses often invoke the compiled C test binaries but add process isolation, timing controls, or environment setup that pure C cannot easily manage.

## The MiniTest Framework ([`test_framework.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/test_framework.h))

Every C test file includes [`tests/test_framework.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_framework.h), which defines the **MiniTest** framework. This header provides assertion macros, test registration infrastructure, and result reporting without external dependencies.

The framework exposes several key functions and macros:

- `test_register(name, function)` – Adds a test function to the global execution list
- `test_run_all()` – Executes every registered test and prints a pass/fail summary
- `assert_int_eq(actual, expected)` – Verifies integer equality
- `assert_true(condition)` – Validates boolean conditions

Support for **parameterized tests**, **benchmark timing**, and **conditional skips** allows the framework to handle stress tests and platform-specific checks without modification.

A standard unit test follows this pattern:

```c
#include "test_framework.h"
#include "my_module.h"

static void test_my_feature(void) {
    /* arrange */
    MyObj *obj = my_obj_new();

    /* act */
    int rc = my_obj_do_something(obj, 42);

    /* assert */
    assert_int_eq(rc, 0);
    assert_true(my_obj_is_valid(obj));
    my_obj_free(obj);
}

/* Register the test with the framework */
int main(void) {
    test_register("my_feature", test_my_feature);
    return test_run_all();
}

```

## Running and Writing Tests

### Executing the Full Test Suite

Local development and CI pipelines use [`scripts/test.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/test.sh) as the central driver. This script compiles the library and all `tests/*.c` files, then executes them sequentially while aggregating results.

```bash

# From the repository root

./scripts/test.sh               # builds and runs every test in tests/

```

The script accepts flags such as `--enable-sanitizer` for memory debugging and `--coverage` for profile generation, which the GitHub Actions workflow invokes during automated checks.

### Running Individual Unit Tests

To debug a specific module without building the entire suite, compile the individual test file against the library:

```bash

# Build only the desired test binary

gcc -Iinclude -Itests -o test_str_util tests/test_str_util.c -lcodebase_memory_mcp
./test_str_util                # prints PASS/FAIL for that file only

```

### Adding New Unit Tests

Contributors extend coverage by following a consistent four-step process:

1. Create [`tests/test_my_new_module.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_my_new_module.c) in the top-level tests directory.
2. Include [`test_framework.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/test_framework.h) and the header of the module under test.
3. Write one or more `static void` test functions using the assert macros.
4. Register them in `main()` with `test_register`.

The generic [`test.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/test.sh) script automatically discovers new `test_*.c` files, compiles them, and executes them on the next CI pass without requiring build system modifications.

## Summary

- The **single `tests/` directory** houses all verification code, keeping discovery simple and consistent.
- **MiniTest framework** ([`test_framework.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/test_framework.h)) provides the assertion macros and registration system for C unit tests.
- **Unit tests** reside in individual `tests/test_*.c` files targeting specific modules like [`test_str_util.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/test_str_util.c) or [`test_store_nodes.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/test_store_nodes.c).
- **Integration tests** concentrate in [`tests/test_integration.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_integration.c) for full-stack pipeline validation.
- **Shell and Python harnesses** handle multi-process and platform-specific scenarios such as [`test_security_strings_allowlist.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/test_security_strings_allowlist.sh) and [`test_mcp_rapid_init.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/test_mcp_rapid_init.py).
- **Centralized execution** through [`scripts/test.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/test.sh) supports local development and CI with sanitizer and coverage options.

## Frequently Asked Questions

### Where are the test files located in codebase-memory-mcp?

All test files reside in the single top-level directory `tests/`. This flat structure contains C source files for unit and integration tests, shell scripts for security validation, and Python harnesses for stress testing, making test discovery straightforward for both developers and CI systems.

### What testing framework does codebase-memory-mcp use for C unit tests?

The project uses a custom **MiniTest** framework defined in [`tests/test_framework.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_framework.h). This lightweight solution provides assertion macros like `assert_int_eq` and `assert_true`, along with `test_register()` and `test_run_all()` functions for test collection and execution, eliminating external dependencies.

### How do I run a single unit test without executing the entire suite?

Compile the specific test file manually using GCC with the appropriate include paths and library linkage. For example, `gcc -Iinclude -Itests -o test_str_util tests/test_str_util.c -lcodebase_memory_mcp` creates an executable that runs only the tests defined in that file, printing individual PASS/FAIL results.

### Does the codebase-memory-mcp test suite support parameterized or conditional tests?

Yes. The MiniTest framework in [`test_framework.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/test_framework.h) supports **parameterized tests**, **benchmark timing**, and **conditional skips**. These features enable stress-testing scripts and platform-specific harnesses to reuse the same assertion infrastructure while controlling execution flow based on runtime conditions.