What Kind of Testing Is Implemented in Codebase-Memory-MCP: A Complete Overview

The codebase-memory-mcp repository employs a four-layer testing strategy that combines Python unit tests, POSIX daemon smoke tests, Windows-specific functional validations, and standalone regression reproduction scripts.

This Model Context Protocol (MCP) implementation for codebase memory uses a comprehensive testing approach to ensure reliability across platforms. The test suite covers everything from isolated Python utility functions to full binary-level integration scenarios involving JSON-RPC communication and process lifecycle management. Understanding the testing architecture helps contributors run the correct validations and debug issues effectively.

Unit Tests with Python's unittest Framework

The foundation of the testing pyramid consists of unit tests located in pkg/pypi/tests/. These use the standard library's unittest module to verify isolated Python logic without requiring the compiled binary.

CLI Payload Selection Logic

The _execution_path() function in pkg/pypi/src/codebase_memory_mcp/_cli.py determines whether to use the Windows launcher based on the platform string. Unit tests verify this logic behaves correctly across operating systems.

import unittest
from pathlib import Path
from codebase_memory_mcp import _cli

class WindowsLauncherSelectionTests(unittest.TestCase):
    def test_windows_uses_adjacent_launcher(self):
        payload = Path("cache") / "0.8.1" / _cli._WINDOWS_PAYLOAD_NAME
        self.assertEqual(
            _cli._execution_path(payload, "win32"),
            payload.with_name(_cli._WINDOWS_LAUNCHER_NAME),
        )

Portable Mutation Classification

Tests also validate _portable_mutation_action(), which parses command-line arguments to determine whether operations like install, update, or uninstall should execute in portable mode. These tests ensure the CLI correctly handles mutation flags before spawning the daemon.

To execute the unit test suite:

python -m unittest discover -s pkg/pypi/tests

Functional and Integration Testing

Beyond unit tests, the repository validates the actual compiled binary through functional tests that exercise the daemon's real-world behavior.

POSIX Daemon Smoke Tests

The file tests/test_daemon_smoke.py contains comprehensive integration tests that spawn the compiled daemon (build/c/codebase-memory-mcp) and communicate via JSON-RPC over Unix domain sockets. These tests validate:

• Rendezvous creation and lock lifecycle management (lock_status, coordination_locks)
• Client-server handshake sequences (initialize and notifications/initialized)
• Tool call execution (list_projects, index_repository) and cancellation semantics (notifications/cancelled)
• Conflict handling when secondary processes attempt connection with mismatched cache roots or build fingerprints
• Audit logging verification (JSON-NDJSON files generated in the cache directory)

The test harness uses a custom McpClient class to abstract RPC interactions:

c1 = McpClient(binary, env, tmpdir / "client-1.err")
c1.send({
    "jsonrpc": "2.0",
    "id": 101,
    "method": "initialize",
    "params": initialize_params,
})
assert_rpc_success(c1.wait_response(101), "client 1 initialize")

Helper functions like assert_rpc_success() and assert_rpc_cancelled() standardize response validation across test cases.

Windows-Specific Functional Tests

Located in tests/windows/, these tests validate platform-specific code paths including launcher detection (test_windows_launcher.py), non-ASCII path handling (test_non_ascii_path.py), and cache dump integrity (test_non_ascii_cache_dump.py). These use the same McpClient harness but exercise Windows-specific implementations using named pipes and mutex communication rather than Unix domain sockets.

Regression and Performance Testing

The repository maintains reproducibility scripts that verify historical bug fixes and monitor resource utilization.

Memory Leak Reproduction Scripts

The file tests/repro/issue832_rss.py provides a deterministic reproduction of the RSS ratchet bug (Issue #832). This standalone script repeatedly indexes a large fixture repository, comparing resident-set-size (RSS) between in-process and supervised subprocess executions to detect memory leaks.

make -f Makefile.cbm cbm        # Build production binary first

python3 tests/repro/issue832_rss.py

# Output:

# cycles=10 files=120

#   0  |   5.2      |   1.1

# ...

This approach ensures that memory optimizations remain effective across releases and prevents regression in the daemon's resource management.

How to Run the Complete Test Suite

Execute the full testing in codebase-memory-mcp with these commands:

Build the binary first (required for integration tests):

make -f Makefile.cbm cbm

Run unit tests:

python -m unittest discover -s pkg/pypi/tests

Execute POSIX daemon smoke tests:

python -m pytest tests/test_daemon_smoke.py

Windows-specific tests (Windows only):

python -m pytest tests/windows/

Summary

• Unit tests in pkg/pypi/tests/test_cli.py validate Python helper functions like _execution_path() and _portable_mutation_action() using the standard unittest framework.
• POSIX daemon smoke tests in tests/test_daemon_smoke.py exercise the compiled binary via JSON-RPC over Unix sockets, testing lock coordination, conflict handling, and cancellation semantics.
• Windows functional tests in tests/windows/ verify platform-specific behaviors including launcher selection and non-ASCII path support.
• Regression scripts like tests/repro/issue832_rss.py provide deterministic bug reproductions and monitor memory usage to prevent RSS ratchet issues.

Frequently Asked Questions

What testing frameworks does codebase-memory-mcp use?

The project uses Python's built-in unittest framework for unit tests and a custom Python harness using subprocess and sockets for integration tests. Unlike many modern Python projects, it does not rely on heavy external testing dependencies for its core validation logic.

Do I need to build the binary before running tests?

You only need to build the binary for functional and integration tests. The unit tests in pkg/pypi/tests/ run against pure Python code and do not require the compiled daemon. However, tests/test_daemon_smoke.py and the Windows-specific tests require build/c/codebase-memory-mcp to exist.

How does the daemon smoke test handle RPC communication?

The smoke test uses a custom McpClient class that spawns the binary and communicates via JSON-RPC over Unix domain sockets (POSIX) or named pipes (Windows). It validates the full lifecycle including initialization, tool calls, cancellation notifications, and proper lock cleanup.

What is the purpose of the RSS reproduction script?

The tests/repro/issue832_rss.py script reproduces Issue #832, a memory ratchet bug where resident set size grew unbounded during repository indexing. The script compares RSS between in-process and subprocess indexing modes, providing side-by-side metrics to verify that the daemon correctly manages memory across multiple indexing cycles.

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