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

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, tests/test_store_nodes.c, and 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 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 performs security-focused integration checks against string handling
• 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)

Every C test file includes 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:

#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 as the central driver. This script compiles the library and all tests/*.c files, then executes them sequentially while aggregating results.

# 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:

# 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 in the top-level tests directory.
2. Include 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 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) 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 or test_store_nodes.c.
• Integration tests concentrate in 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 and test_mcp_rapid_init.py.
• Centralized execution through 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}