How to Run Tests in thedotmack/claude-mem: A Complete Guide

Run npm run test to execute the full Bun-based test suite, or use targeted scripts like npm run test:sqlite to run specific layers.

The thedotmack/claude-mem repository ships with a comprehensive test suite that validates every layer of the system—from low-level SQLite helpers to the full-stack worker API. The tests are written with Bun’s built-in test runner and are organized under the top-level tests/ directory, using the describe/it API pattern.

Test Architecture and Organization

The test suite is modularized by architectural layer, making it easy to isolate specific subsystems during development.

Layer	Location	Coverage Focus
Infrastructure	tests/infrastructure/	Process manager, health monitor, graceful shutdown
Server / HTTP API	tests/server/	Express server startup, routing, error handling
Worker Core	tests/worker/	Agent logic, middleware, session cleanup
Search Strategies	tests/worker/search/strategies/	SQLite, Chroma, and Hybrid search implementations
Context & Formatting	tests/context/	Observation compiler, markdown formatter
SQLite Data Layer	tests/sqlite/	Sessions, observations, prompts
Integration / E2E	tests/integration/	Worker API endpoints, hook execution, vector sync
CLI / SDK	tests/sdk-agent-resume.test.ts	Resume-agent behavior

All test files follow the *.test.ts naming convention and utilize Bun’s native testing primitives.

Prerequisites

Before executing tests, ensure your environment meets the following requirements:

1. Node.js ≥ 18 and Bun ≥ 1.0 (specified in the engines field of package.json)
2. Dependencies installed via npm install or bun install
3. No additional environment variables are required for unit tests; they use in-memory or temporary SQLite databases

Running the Test Suite

The repository defines npm scripts in package.json (line 79 for the main test command) that delegate to Bun’s test runner.

Running All Tests

To execute the complete suite:

npm run test

This runs every *.test.ts file under the tests/ directory and reports results across all architectural layers.

Targeted Test Execution

For faster feedback during development, use the scoped scripts:

# SQLite data layer only

npm run test:sqlite

# Worker agents

npm run test:agents

# Search strategies (SQLite, Chroma, Hybrid)

npm run test:search

# Context and formatting

npm run test:context

# Infrastructure components

npm run test:infra

# Server and HTTP API

npm run test:server

# Integration and E2E tests

npm run test:integration

To run a single test file directly:

bun test tests/worker/search/strategies/sqlite-search-strategy.test.ts

Watch Mode and Coverage

For iterative development, use Bun’s watch mode to re-run tests on file changes:

bun test --watch

To generate coverage reports:

bun test --coverage

This produces an LCOV report under the coverage/ directory.

Key Test Files and Examples

The following files demonstrate the breadth and depth of the test suite:

• tests/worker/search/strategies/sqlite-search-strategy.test.ts – Validates the SQLite search implementation, including filter-only queries and type-specific searches
• tests/integration/worker-api-endpoints.test.ts – End-to-end HTTP API validation for the worker service
• tests/sqlite/observations.test.ts – Unit tests for the SQLite observations data layer
• tests/server/server.test.ts – Express server startup and routing tests
• package.json – Contains all npm script definitions on line 79

Summary

• thedotmack/claude-mem uses Bun’s native test runner with tests organized under tests/
• Run the full suite with npm run test or target specific layers with scripts like npm run test:sqlite
• Tests cover infrastructure, server APIs, worker logic, search strategies, and SQLite data layers
• Use bun test --watch for development and bun test --coverage for coverage reports

Frequently Asked Questions

What test runner does thedotmack/claude-mem use?

The repository uses Bun’s built-in test runner, which provides a Jest-compatible describe/it API without requiring additional dependencies. This is defined in the test scripts within package.json.

Do I need to set up a database to run the tests?

No. The unit tests use in-memory or temporary SQLite databases that are automatically created and cleaned up during test execution. No external database configuration or environment variables are required for the standard test suite.

How do I run only the search strategy tests?

Use the targeted npm script: npm run test:search. This executes all tests under tests/worker/search/, including the SQLite, Chroma, and Hybrid strategy implementations. You can also run a single strategy file directly with bun test tests/worker/search/strategies/sqlite-search-strategy.test.ts.

Can I run tests in watch mode during development?

Yes. While the npm scripts provide convenient entry points, you can use Bun’s native watch mode by running bun test --watch. This monitors file changes and automatically re-runs the relevant tests, providing rapid feedback during iterative development.

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