Role of the Tests Directory in DeusData codebase-memory-mcp: Complete Guide

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 every major component from MCP protocol handling to security sandboxing.

The codebase-memory-mcp repository by DeusData implements a memory-backed Model Context Protocol (MCP) server for codebase indexing and retrieval. Within this architecture, the tests directory functions as the primary verification layer, ensuring that changes to the core protocol, indexing pipeline, or graph storage layers do not introduce regressions. This testing infrastructure spans multiple languages and platforms to guarantee cross-platform reliability.

Overview of the Tests Architecture

The tests directory employs a lightweight custom framework defined in tests/test_framework.h and orchestrated through tests/test_main.c. Unlike heavy external dependencies, this minimal harness keeps the build system simple while providing essential assertions, colored output, and selective test filtering.

The directory organizes validation into distinct functional areas:

• Core MCP protocol – End-to-end command handling and worker spawning
• Indexing pipeline – Repository scanning and incremental updates
• Language extraction – Multi-language parsing and LSP resolution
• Graph storage – SQLite-backed persistence and Cypher query execution
• Security – Subprocess isolation and socket leakage prevention
• Platform-specific – Windows compatibility and non-ASCII path handling

Core Testing Components

MCP Protocol and CLI Validation

The file tests/test_mcp.c validates end-to-end handling of MCP commands, ensuring proper worker spawning and response serialization. Complementing this, tests/test_cli.c verifies argument parsing, sub-command execution, and platform-specific entry points for the command-line interface.

// From tests/test_mcp.c - validating protocol message handling
TEST(test_mcp_command_handling) {
    struct mcp_message *msg = mcp_message_new();
    ASSERT_NOT_NULL(msg);
    ASSERT_EQ(mcp_parse_command(msg, "initialize"), 0);
    PASS();
}

Indexing Pipeline Verification

Repository indexing logic undergoes rigorous validation in tests/test_pipeline.c. These tests verify full repository indexing, incremental updates, and resilience against malformed inputs. The suite ensures that the pipeline correctly handles broken source files without crashing the entire indexing process.

Language Extraction and LSP Resolution

Multi-language support is tested through tests/test_extraction.c and language-specific files such as tests/test_java_lsp.c. These files validate correct parsing of source files, symbol table construction, and cross-language reference resolution necessary for accurate codebase navigation.

// From tests/test_extraction.c - validating symbol extraction
TEST(test_extract_function_symbols) {
    struct source_file *sf = load_source("test_data/sample.py");
    ASSERT_NOT_NULL(sf);
    ASSERT_GT(symbol_count(sf), 0);
    ASSERT_STR_EQ(get_symbol_name(sf, 0), "main");
    PASS();
}

Graph Store and Query Layer

Database persistence and query correctness are validated in tests/test_store_nodes.c and tests/test_cypher.c. These tests exercise SQLite-backed graph persistence, node and edge CRUD operations, and Cypher-style query execution to ensure the graph database layer maintains data integrity under concurrent access.

Security and Sandboxing

Critical security guarantees are enforced through tests/test_security.c. This suite verifies isolation of subprocesses, checks for socket leakage, and ensures safe handling of untrusted inputs. Platform-specific guards allow skipping tests incompatible with the current environment:

// From tests/test_security.c - platform-specific test skipping
#ifdef _WIN32
SKIP_PLATFORM("Unix socket test - disabled on Windows")
#else
TEST(test_unix_socket_isolation) {
    int fd = create_isolated_socket();
    ASSERT_GE(fd, 0);
    ASSERT_FALSE(socket_leaks_to_parent(fd));
    PASS();
}
#endif

Test Framework Implementation

Custom C Test Harness

Rather than importing external testing libraries, the project uses a minimal framework defined in tests/test_framework.h. This header provides assertion macros like ASSERT_NOT_NULL, ASSERT_EQ, and ASSERT_STR_EQ, along with test registration macros.

// From tests/test_hash_table.c - typical test definition pattern
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();
}

Running Test Suites

The entry point tests/test_main.c discovers available test suites and supports command-line filtering. Developers can execute the full suite or target specific components:

// From tests/test_main.c - selective suite execution
int main(int argc, char **argv) {
    g_suite_argc = argc;
    g_suite_argv = argv;

    RUN_SELECTED_SUITE(hash_table);
    RUN_SELECTED_SUITE(store_nodes);
    RUN_SELECTED_SUITE(mcp);
    // ...
    TEST_SUMMARY();
}

Execution from the build directory supports subset filtering:

# Run all tests

./test_main

# Run only storage and graph tests

./test_main test_store_nodes test_cypher

Platform-Specific and Auxiliary Tests

Windows Compatibility

The subdirectory tests/windows/ contains Python-based helpers for platform-specific validation. The file tests/windows/test_non_ascii_path.py verifies correct handling of Unicode filenames, a common source of bugs on Windows systems:

# From tests/windows/test_non_ascii_path.py

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"

Performance and Compression

Storage efficiency tests reside in tests/test_zstd.c and tests/test_lz4.c, validating the correctness of ZSTD and LZ4 compression streams used for both storage optimization and network transfer reduction.

Utility Libraries

Low-level infrastructure is verified in tests/test_str_util.c, ensuring that string manipulation, memory management, and data structure helpers used throughout the codebase operate correctly under edge cases like null inputs or maximum buffer sizes.

Summary

The tests directory in DeusData codebase-memory-mcp fulfills three essential architectural roles:

• Verification – Guarantees that new changes do not break existing functionality across the MCP protocol, indexing pipeline, and graph storage layers
• Documentation – Provides concrete usage patterns for public APIs, demonstrating how to invoke the MCP server, LSP resolver, and graph query interfaces
• Specification – Acts as an executable specification of the system’s contract, particularly for security-critical code involving worker isolation and socket handling

Frequently Asked Questions

What testing framework does codebase-memory-mcp use?

The project uses a minimal custom C testing framework defined in tests/test_framework.h rather than external libraries like Google Test or CMocka. This custom harness provides assertion macros, test registration, and colored output while maintaining build simplicity. The entry point in tests/test_main.c orchestrates test discovery and execution.

How do I run specific test suites in codebase-memory-mcp?

Pass the suite names as command-line arguments to the test binary. For example, ./test_main test_store_nodes test_cypher executes only the graph storage and query tests. Without arguments, ./test_main runs the complete test suite including protocol validation, security checks, and compression tests.

Does the tests directory include platform-specific validation?

Yes, the directory includes tests/windows/ for Windows-specific sanity checks, primarily using Python scripts to verify non-ASCII filename handling and CLI Unicode support. The C tests use preprocessor guards like #ifdef _WIN32 to skip platform-incompatible tests, such as Unix socket isolation checks on Windows systems.

What security aspects does the test suite cover?

The file tests/test_security.c validates subprocess isolation, prevents socket leakage between workers, and ensures safe handling of untrusted inputs. These tests act as executable security specifications, verifying that the MCP server maintains proper sandboxing boundaries when executing external language servers or processing arbitrary repository content.

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