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

> Explore the comprehensive four-layer testing strategy in codebase-memory-mcp, including Python unit tests, POSIX daemon smoke tests, Windows functional validations, and regression scripts.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: testing-overview
- Published: 2026-07-26

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.

```python
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:

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```python
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/test_windows_launcher.py)), **non-ASCII path handling** ([`test_non_ascii_path.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/test_non_ascii_path.py)), and **cache dump integrity** ([`test_non_ascii_cache_dump.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.

```bash
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):

```bash
make -f Makefile.cbm cbm

```

**Run unit tests:**

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

```

**Execute POSIX daemon smoke tests:**

```bash
python -m pytest tests/test_daemon_smoke.py

```

**Windows-specific tests** (Windows only):

```bash
python -m pytest tests/windows/

```

## Summary

- **Unit tests** in [`pkg/pypi/tests/test_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.