How to Run Tests for codebase-memory-mcp: Complete Guide

Run ./scripts/test.sh from the repository root to execute the full test suite in parallel, or use CBM_SKIP_VM=1 ./scripts/test.sh to exclude Windows VM tests.

The codebase-memory-mcp project ships with a comprehensive test harness that validates the binary, CLI, daemon, and language-specific analysis features. Understanding how to run tests for codebase-memory-mcp ensures you can verify changes locally before submitting contributions. The test infrastructure automatically handles binary builds, daemon coordination, and parallel execution across multiple platforms.

Overview of the Test Infrastructure

The testing framework centers on two shell scripts located in the scripts/ directory. According to the DeusData/codebase-memory-mcp source code, these scripts orchestrate the entire validation process:

• scripts/test.sh – The high-level entry point that discovers the test runner, triggers builds when necessary, and invokes the parallel harness.
• scripts/run-tests-parallel.sh – The core execution engine that runs all registered test suites concurrently, including native Linux/macOS suites and Windows VM-based suites.

Individual test contracts reside in the tests/ directory (e.g., test_worker_watchdog.sh, test_venue_parity_contract.sh), while infrastructure logs write to test-infrastructure/.

Step-by-Step Test Execution

Build the Binary (Optional)

The test harness automatically builds the binary if it cannot locate a recent build in the build/ directory. However, for faster iteration, you can pre-build using scripts/build.sh:

# Build the static binary for your platform

./scripts/build.sh

# Or build with UI support

./scripts/build.sh --with-ui

Run the Full Test Suite

Execute the master test driver to validate all components:

./scripts/test.sh

This command automatically starts the coordination daemon (if not running), indexes the repository, and executes every registered suite in parallel. The script exits with a non-zero status if any suite fails.

To skip Windows VM tests on non-Windows hosts:

CBM_SKIP_VM=1 ./scripts/test.sh

Run Specific Test Suites

For targeted debugging, invoke scripts/run-tests-parallel.sh directly with a specific suite name:

./scripts/run-tests-parallel.sh ./build/c/codebase-memory-mcp python-tests

You can also use the Makefile target defined in Makefile.cbm:

make test

Environment Variables for Test Configuration

The test harness respects several environment variables that modify its behavior without editing scripts:

• CBM_ALLOW_MISSING_BIN – Set to 1 to skip the binary-building step and run tests against whatever binary exists on your $PATH.
• CBM_TEST_PARALLELISM – Controls the number of parallel jobs passed to run-tests-parallel.sh. Defaults to the number of CPUs.
• CBM_SKIP_VM – Set to 1 to skip the Windows-VM-based suites, useful for local development on Linux or macOS.

Example usage with multiple variables:

CBM_SKIP_VM=1 CBM_TEST_PARALLELISM=4 ./scripts/test.sh

Test Output and Logging

After execution, inspect the results in the test-infrastructure/ directory. The scripts print a concise summary to stdout while writing detailed logs to subdirectories like test-infrastructure/vm/ for Windows VM runs.

If failures occur, the harness prints the failing suite's name and exits with a non-zero status. Re-run individual failing suites by passing their names to scripts/run-tests-parallel.sh as shown in the step-by-step section above.

Summary

• Execute ./scripts/test.sh to run the complete test suite across all platforms.
• Use CBM_SKIP_VM=1 to exclude Windows VM tests when running on Linux or macOS.
• Pre-build binaries with ./scripts/build.sh to skip automatic compilation during test runs.
• Target specific suites by passing names directly to scripts/run-tests-parallel.sh.
• Review detailed logs in test-infrastructure/ after execution completes.

Frequently Asked Questions

How do I run tests without rebuilding the binary every time?

Set the CBM_ALLOW_MISSING_BIN environment variable to 1. This tells scripts/test.sh to use the existing binary on your $PATH rather than checking for or building a fresh binary in the build/ directory.

Can I run tests on Linux if I don't have Windows virtualization?

Yes. Export CBM_SKIP_VM=1 before running ./scripts/test.sh. This skips the Windows-VM-based suites while still executing all native Linux/macOS test contracts and language-specific analysis validations.

Where does the test harness store logs and diagnostics?

The framework writes detailed output to the test-infrastructure/ directory at the repository root. This includes VM-specific logs under test-infrastructure/vm/ and general coordination logs from the daemon and indexing processes.

What happens if the coordination daemon isn't running when I start tests?

The test harness automatically starts the coordination daemon if it detects that it is not already running. It also handles repository indexing before exercising graph-related CLI commands, ensuring a fresh test environment without manual intervention.

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