Role of the Tests Directory in DeusData/codebase-memory-mcp: Architecture and Usage

The tests directory in DeusData/codebase-memory-mcp serves as the comprehensive quality-assurance suite, containing unit, integration, and system tests written primarily in C that validate the MCP protocol, indexing pipeline, graph store, and security boundaries through a custom lightweight framework.

The tests directory is the backbone of reliability for the codebase-memory-mcp repository, housing exhaustive automated checks that span from low-level data structures to full-stack UI validation. This directory contains a custom C-based testing harness and extensive test suites that ensure every component—from MCP message handling to graph database persistence—functions correctly across platforms.

Core Testing Areas in the Tests Directory

The tests directory organizes validation across every major subsystem of the project. Each area targets specific functionality critical to the Model Context Protocol (MCP) implementation.

MCP Protocol and CLI Validation

Core protocol tests reside in tests/test_mcp.c, which validates end-to-end handling of MCP commands, worker spawning, and response serialization. The CLI testing in tests/test_cli.c verifies argument parsing, sub-command execution, and platform-specific entry points, ensuring the command-line interface behaves correctly across different operating systems.

Indexing Pipeline and Language Extraction

The indexing system is validated through tests/test_pipeline.c, which tests full repository indexing, incremental updates, and resilience to broken or malformed inputs. Language extraction tests in tests/test_extraction.c and language-specific files such as tests/test_java_lsp.c verify correct parsing of source files, symbol tables, and cross-language reference resolution.

Graph Store and Query Layer

Graph persistence is tested in tests/test_store_nodes.c and tests/test_cypher.c, covering SQLite-backed graph storage, node/edge CRUD operations, and Cypher-style query correctness. These tests ensure the graph database layer maintains data integrity during complex queries and transactions.

Security and Platform-Specific Testing

Security-critical code is validated in tests/test_security.c, which checks isolation of subprocesses, socket leakage, and safe handling of untrusted inputs. UI and HTTP services are tested in tests/test_ui.c and tests/test_httpd.c, verifying Graph UI rendering and server lifecycle management. Platform-specific edge cases for Windows are handled in tests/windows/test_non_ascii_path.py and related files, ensuring correct behavior with non-ASCII filenames and I/O quirks.

Performance and Utility Validation

Compression algorithms used for storage and network transfer are verified in tests/test_zstd.c and tests/test_lz4.c. Low-level helper libraries undergo validation in tests/test_str_util.c and tests/test_hash_table.c, ensuring string manipulation, memory management, and data structure operations remain stable.

The Custom Test Framework Implementation

The tests directory implements a minimal custom testing framework defined in tests/test_framework.h and orchestrated by tests/test_main.c. This design avoids external dependencies while providing assertion macros, colored output, and selective test execution.

Defining Test Cases

Tests use macros defined in tests/test_framework.h to create self-registering test functions with automatic assertion checking:

TEST(test_hash_table_basic) {
    struct hash_table *ht = hash_table_new(64);
    ASSERT_NOT_NULL(ht);
    ASSERT_EQ(hash_table_insert(ht, "key", "value"), 0);
    const char *v = hash_table_lookup(ht, "key");
    ASSERT_STR_EQ(v, "value");
    PASS();
}

Source: tests/test_hash_table.c

Platform-Specific Conditional Logic

The framework supports skipping tests on incompatible platforms using preprocessor directives:

#ifdef _WIN32
SKIP_PLATFORM("Windows-only test – disabled on Linux")
#else
TEST(test_unix_socket_isolation) { … }
#endif

Source: tests/test_security.c

Test Discovery and Execution

The tests/test_main.c file handles test discovery, command-line filtering, and aggregation of statistics:

int main(int argc, char **argv) {
    g_suite_argc = argc;
    g_suite_argv = argv;

    RUN_SELECTED_SUITE(hash_table);
    RUN_SELECTED_SUITE(store_nodes);
    // …
    TEST_SUMMARY();
}

Source: tests/test_main.c

Helper Scripts for Complex Scenarios

Python scripts in tests/windows/ handle complex platform validation, such as non-ASCII path handling:

def test_non_ascii_path(tmp_path):
    path = tmp_path / "δοκιμή.txt"
    path.write_text("content", encoding="utf-8")
    assert path.read_text(encoding="utf-8") == "content"

Source: tests/windows/test_non_ascii_path.py

Running the Tests Suite

The test runner compiles into a single executable that supports flexible execution patterns. Developers can run the entire suite or filter for specific components:

# Run every test (default)

./test_main

# Run only specific suites

./test_main test_store_nodes test_cypher

This command-line interface, implemented in tests/test_main.c, enables rapid iteration during development and targeted regression testing during continuous integration.

Three Essential Architectural Roles of the Tests Directory

The tests directory serves three critical functions beyond simple bug detection:

1. Verification – Guarantees that new changes do not break existing functionality (regression safety). Every commit is validated against the suite in tests/test_mcp.c and related files to ensure protocol compatibility.

2. Documentation – Shows concrete usage patterns for public APIs. Reading tests/test_extraction.c or tests/test_pipeline.c reveals how to invoke the MCP server or configure the LSP resolver correctly.

3. Specification – Acts as an executable specification of the system’s contract, particularly for security-critical code. The checks in tests/test_security.c define the expected behavior for worker isolation and socket handling that the implementation must satisfy.

Summary

The tests directory in DeusData/codebase-memory-mcp is the primary quality-assurance mechanism for the entire codebase:

• Comprehensive coverage spans MCP protocol handling, CLI operations, indexing pipelines, language extraction, graph storage, security boundaries, and platform-specific edge cases.
• Custom framework in tests/test_framework.h and tests/test_main.c provides lightweight test execution without external dependencies.
• Critical files include tests/test_mcp.c for protocol validation, tests/test_security.c for isolation checks, and tests/test_pipeline.c for indexing verification.
• Executable documentation demonstrates proper API usage for components like the graph store and compression utilities.

Frequently Asked Questions

What testing framework does codebase-memory-mcp use?

The repository uses a custom lightweight C framework defined in tests/test_framework.h rather than external libraries like CMocka or Unity. This framework provides assertion macros (ASSERT_EQ, ASSERT_NOT_NULL), test registration via the TEST() macro, and colored console output. The tests/test_main.c file serves as the runner that discovers and executes registered suites.

How do I run a subset of tests in the tests directory?

Pass the specific test suite names as command-line arguments to the compiled test_main binary. For example, ./test_main test_store_nodes test_cypher executes only the graph store and Cypher query tests. This filtering mechanism is implemented in tests/test_main.c and allows developers to focus on specific subsystems during debugging.

What security aspects are validated in the tests directory?

Security testing in tests/test_security.c validates subprocess isolation, socket leakage prevention, and safe handling of untrusted inputs. The tests verify that worker processes are properly sandboxed and that file descriptors are not leaked across process boundaries. Platform-specific security behaviors are also checked in tests/windows/ to ensure consistent isolation across operating systems.

Are there platform-specific tests for Windows?

Yes, the tests/windows/ directory contains Python and shell scripts that validate Windows-specific behaviors, such as handling non-ASCII filenames in tests/windows/test_non_ascii_path.py. These tests ensure the indexing pipeline and CLI correctly process Unicode paths and handle Windows-specific I/O quirks that differ from Unix-like systems.

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