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

> Learn how to run tests in thedotmack/claude-mem. Execute the full Bun test suite with npm run test or target specific layers like sqlite with npm run test:sqlite.

- Repository: [Alex Newman/claude-mem](https://github.com/thedotmack/claude-mem)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/thedotmack/claude-mem/blob/main/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`](https://github.com/thedotmack/claude-mem/blob/main/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`](https://github.com/thedotmack/claude-mem/blob/main/package.json) (line 79 for the main test command) that delegate to Bun’s test runner.

### Running All Tests

To execute the complete suite:

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

```bash

# 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:

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

```bash
bun test --watch

```

To generate coverage reports:

```bash
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`](https://github.com/thedotmack/claude-mem/blob/main/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`](https://github.com/thedotmack/claude-mem/blob/main/tests/integration/worker-api-endpoints.test.ts)** – End-to-end HTTP API validation for the worker service
- **[`tests/sqlite/observations.test.ts`](https://github.com/thedotmack/claude-mem/blob/main/tests/sqlite/observations.test.ts)** – Unit tests for the SQLite observations data layer
- **[`tests/server/server.test.ts`](https://github.com/thedotmack/claude-mem/blob/main/tests/server/server.test.ts)** – Express server startup and routing tests
- **[`package.json`](https://github.com/thedotmack/claude-mem/blob/main/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`](https://github.com/thedotmack/claude-mem/blob/main/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.