Testing Infrastructure

Relevant source files

• .claude/commands/release/beta.md
• .claude/commands/release/changelog.md
• .claude/commands/release/release-check.md
• .claude/commands/release/release.md
• .github/workflows/claude-issue-triage.yml
• .github/workflows/test.yml
• justfile
• plugins/codex/hooks/test_codex_pre_compact.py
• plugins/codex/hooks/test_codex_session_start.py
• scripts/edit-issue-labels.sh
• scripts/update_versions.py
• src/basic_memory/api/container.py
• src/basic_memory/api/v2/routers/prompt_router.py
• src/basic_memory/deps/__init__.py
• src/basic_memory/deps/config.py
• src/basic_memory/deps/db.py
• src/basic_memory/deps/importers.py
• src/basic_memory/deps/projects.py
• src/basic_memory/deps/repositories.py
• test-int/conftest.py
• test-int/semantic/conftest.py
• test-int/semantic/corpus.py
• test-int/semantic/metrics.py
• test-int/semantic/test_embedding_provider_reuse.py
• test-int/semantic/test_real_fastembed_reranker.py
• test-int/semantic/test_reranker_latency.py
• test-int/semantic/test_reranker_quality.py
• tests/api/v2/conftest.py
• tests/cli/conftest.py
• tests/mcp/conftest.py
• tests/test_claude_issue_triage.py
• tests/test_claude_plugin_hooks.py
• tests/test_deps.py
• tests/test_update_versions.py

Basic Memory employs a robust, three-tier testing strategy designed to ensure reliability across its local-first architecture. The suite covers everything from isolated unit logic to end-to-end MCP tool execution, supporting both SQLite and PostgreSQL backends.

Three-Tier Test Suite

The codebase organizes tests into three distinct directories based on their scope and execution speed justfile38-45:

Tier	Directory	Focus	Mocking
Unit	tests/	Individual components, services, and markdown parsing logic.	Heavy use of mocks and in-memory databases justfile48-56
Integration	test-int/	Complete flow: MCP Client → MCP Server → FastAPI → Database.	No mocks; uses real filesystem SQLite or Postgres test-int/conftest.py5-6
Bughunt	test-int/bughunt_fixes/	Regression tests for specific bugs identified in production or CLI tool parity.	Real-world scenarios mirroring the integration tier.

Integration Test Data Flow

Integration tests utilize an ASGITransport to bridge the MCP server and the FastAPI application within a single process, avoiding the overhead of real network sockets test-int/conftest.py13 test-int/conftest.py71 This allows testing the full API stack, including middleware and dependency injection, without requiring a live network interface.

Flow Diagram: Integration Test Execution

Sources: test-int/conftest.py12-17 test-int/conftest.py71 test-int/conftest.py87-88 tests/mcp/conftest.py69-72

Database Backends & Testcontainers

Basic Memory supports dual backends justfile19-21 By default, tests run against SQLite for speed justfile42 To test PostgreSQL parity, the suite uses testcontainers to manage ephemeral Docker instances.

PostgreSQL Testing Lifecycle

1. Detection: Tests check BASIC_MEMORY_TEST_POSTGRES=1 to toggle the backend test-int/conftest.py108-109
2. Provisioning: postgres_container fixture spins up pgvector/pgvector:pg16 to support vector search extensions test-int/conftest.py125-127
3. External Overrides: If BASIC_MEMORY_TEST_POSTGRES_URL is set, the suite uses the provided server instead of spinning up a container test-int/conftest.py180-190
4. Cleanup: Ephemeral tables such as search_vector_embeddings and search_vector_index are cleared between runs test-int/conftest.py171-175

Sources: justfile19-29 test-int/conftest.py108-127 test-int/conftest.py180-190

Pytest Fixtures and conftest Patterns

Global Fixtures

• db_backend: Determines the target database engine (sqlite vs postgres) test-int/conftest.py102-110
• postgres_container: Manages the Docker lifecycle for Postgres using PostgresContainer test-int/conftest.py113-127
• cleanup_global_db_after_test: An autouse fixture that calls db.shutdown_db() to prevent non-daemon aiosqlite workers from hanging after tests finish test-int/conftest.py129-141

Specialized Fixtures

• CLI Isolation: isolated_home prevents tests from polluting the user's actual ~/.basic-memory directory by mocking HOME and BASIC_MEMORY_HOME tests/cli/conftest.py15-37
• Routing Isolation: clean_routing_env ensures environment variables like BASIC_MEMORY_FORCE_LOCAL do not leak between test cases test-int/conftest.py144-153
• FastAPI Dependency Overrides: The app fixture in MCP tests applies dependency_overrides for get_app_config and get_engine_factory to inject test-specific configuration tests/mcp/conftest.py50-65
• Search Indexing: init_search_index explicitly calls SearchService.init_search_index to prepare FTS5 or pgvector tables for search-dependent tests tests/mcp/conftest.py89-92

Sources: test-int/conftest.py129-153 tests/cli/conftest.py15-37 tests/mcp/conftest.py50-92

Testmon and Performance Optimization

To maintain a fast developer loop, the project uses pytest-testmon to track which tests are affected by code changes .github/workflows/test.yml19-23

• CI Selection: In GitHub Actions, BASIC_MEMORY_TESTMON_FLAGS selects only impacted tests for branch builds using --testmon --testmon-forceselect, while running the full suite on main with --testmon-noselect .github/workflows/test.yml23
• CI Sharding: The Postgres unit suite is sharded across parallel jobs in CI using pytest-split to reduce wall-clock time .github/workflows/test.yml220-226
• Local Caching: The testmon-seed and testmon-refresh recipes in the justfile manage the synchronization of the .testmondata cache justfile87-97

Entity Mapping: Test Orchestration

Sources: .github/workflows/test.yml19-23 .github/workflows/test.yml220-226 justfile87-97 test-int/conftest.py71

Running Tests

Tests are executed using pytest, typically via the just command runner justfile17-36

Common Commands

• Run all tests: just test (Runs both SQLite and Postgres suites) justfile39
• SQLite Unit Tests: just test-unit-sqlite justfile48-49
• Postgres Unit Tests: just test-unit-postgres (Uses testcontainers) justfile53-56
• Impacted Tests Only: just fast-test or just testmon justfile79-85
• MCP Smoke Test: just test-smoke for a fast end-to-end validation justfile103-104
• Read Cache Tests: just test-read-cache runs semantic read-cache suite against Redis justfile108-109

Environment Variables

• BASIC_MEMORY_TEST_POSTGRES=1: Switches the test backend to Postgres justfile56
• BASIC_MEMORY_TEST_POSTGRES_URL: Overrides the auto-provisioned Postgres container with a specific URL for CI test-int/conftest.py180-182

Sources: justfile38-109 test-int/conftest.py108-110 test-int/conftest.py180-190