Vault Cortex utilizes a comprehensive test suite powered by vitest, covering every layer from low-level Markdown parsing to the high-level CLI scaffolding and MCP prompt assembly. The infrastructure emphasizes table-driven tests for logic-heavy parsers and integration-style harnesses for stateful components like the search index, OAuth provider, and MCP prompts.
The testing environment is defined in vitest.config.ts, which configures the test runner for the TypeScript environment, including src/, cli/src/, and scripts/ directories vitest.config.ts1-13
Tests follow a behavioral naming convention, typically colocated in __tests__/ directories within their respective subsystems. This ensures that the test suite serves as living documentation for the expected behavior of each module (e.g., search-index.test.ts for the search subsystem src/vault-mcp/search/__tests__/search-index.test.ts1-21).
Because MCP prompts are highly dynamic—querying the search index, memory store, and link graph at invocation time—the project uses a specialized harness in src/vault-mcp/mcp-core/__tests__/prompt-test-harness.ts.
Key features of the harness:
setupVault: Creates a temporary filesystem vault using mkdtemp, populates it with fixture notes, and initializes an in-memory SearchIndex via createSearchIndex(":memory:").recordingLogger: A stub logger that captures every call into a sink, merging child properties to allow tests to assert on specific log levels and data payloads emitted during prompt execution.captureRegistration: Stubs the McpServer to capture registerPrompt calls, allowing tests to extract and invoke the underlying handlers directly.Sources: vitest.config.ts1-13 src/vault-mcp/mcp-core/__tests__/prompt-test-harness.ts1-189
The search index tests in src/vault-mcp/search/__tests__/search-index.test.ts verify the SQLite schema, FTS5 integration, and sqlite-vec vector operations.
createSearchIndex successfully initializes FTS5 and vector tables, loading the sqlite-vec extension during construction src/vault-mcp/search/__tests__/search-index.test.ts205-227installStatementPoison to verify that note updates are atomic across multiple tables (notes, links, tasks). If a task insertion fails, the note metadata update is rolled back src/vault-mcp/search/__tests__/search-index.test.ts90-124 src/vault-mcp/search/__tests__/search-index.test.ts284-332bytes) and leading_callout blocks are correctly surfaced in folder discovery and search results src/vault-mcp/search/__tests__/search-index.test.ts229-245Prompt tests focus on the "Live Data" aspect of Vault Cortex, ensuring that prompts correctly assemble vault state at the moment of the request.
daily-review: The prompt uses search.modifiedOnDate to find activity and search.getOutgoingLinks to detect broken links. Tests verify it resolves dates correctly via Luxon and handles note existence checks.daily-review prompt queries the task index for due or overdue tasks using a before filter on the next day's date.Tests in src/vault-mcp/vault-operations/__tests__/vault-filesystem.test.ts validate safety primitives.
atomicWriteFile is tested to ensure it stages to a .tmp file and renames it, leaving no artifacts on success and cleaning up on failure src/vault-mcp/vault-operations/__tests__/vault-filesystem.test.ts55-78atomicWriteFileExclusive is tested for EEXIST collisions, ensuring no-clobber behavior even on filesystems without hard-link support (Windows/Docker bind mounts) using the wx flag fallback src/vault-mcp/vault-operations/__tests__/vault-filesystem.test.ts80-146resolveSafePath correctly blocks attempts to escape the vault root using ../ variants src/vault-mcp/vault-operations/__tests__/vault-filesystem.test.ts148-176OAuth tests verify the integrity of the 2.1 provider and JWT token handling.
oauth-provider.test.ts verify that refresh tokens rotate on use and reset the 60-day expiry window, while expired tokens are purged on read src/vault-mcp/oauth/oauth-provider.ts189-210initDb function creates the necessary clients, refresh_tokens, and revoked_tokens tables in the SQLite database src/vault-mcp/oauth/oauth-provider.ts62-97The CLI test suite validates the interactive and non-interactive flows for lifecycle management and setup.
init.test.ts validates flag validation (e.g., --yes requiring --vault-path) and conflict policies for existing configurations cli/src/__tests__/init.test.ts31-63upgrade.test.ts and lifecycle.test.ts verify Docker daemon checks, health polling logic using the PORT from .env, and container teardown safety cli/src/__tests__/upgrade.test.ts45-57 cli/src/__tests__/lifecycle.test.ts40-71get-sync-token.test.ts verifies the captureObsidianToken logic, ensuring it correctly reads and trims the auth_token file from the obsidian-headless config mount cli/src/__tests__/get-sync-token.test.ts42-69Sources: src/vault-mcp/search/__tests__/search-index.test.ts1-332 src/vault-mcp/vault-operations/__tests__/vault-filesystem.test.ts1-210 src/vault-mcp/oauth/oauth-provider.ts1-210 cli/src/__tests__/init.test.ts1-137 cli/src/__tests__/upgrade.test.ts1-221 cli/src/__tests__/lifecycle.test.ts1-208 cli/src/__tests__/get-sync-token.test.ts1-192
The following diagram illustrates how the prompt-test-harness.ts bridges the gap between natural language test requirements and the underlying code entities.
Diagram: Prompt Test Infrastructure Mapping
Sources: src/vault-mcp/mcp-core/__tests__/prompt-test-harness.ts124-189 src/vault-mcp/search/search-queries.ts152-210
This diagram shows how search-index.test.ts exercises specific SQLite and parser logic.
Diagram: Search Test Coverage Mapping
Sources: src/vault-mcp/search/__tests__/search-index.test.ts90-245 src/vault-mcp/search/search-index.ts1-100
| Subsystem | Primary Test File | Key Patterns |
|---|---|---|
| Search Index | search-index.test.ts | In-memory SQLite, sqlite-vec loading, statement poisoning for atomicity search-index.test.ts90-124 |
| Vault Ops | vault-filesystem.test.ts | atomicWriteFile safety, resolveSafePath traversal checks vault-filesystem.test.ts55-176 |
| OAuth | oauth-provider.test.ts | Sliding expiry, rotation, and schema initialization oauth-provider.ts62-97 |
| CLI Init | init.test.ts | Flag validation, .env scaffolding, and connection message routing init.test.ts31-166 |
| CLI Lifecycle | lifecycle.test.ts | Docker runner stubs for runDown, runLogs, and runRestart lifecycle.test.ts40-208 |
| Prompts | prompt-test-harness.ts | setupVault integration, recordingLogger sink prompt-test-harness.ts1-189 |
Sources: src/vault-mcp/search/__tests__/search-index.test.ts1-332 src/vault-mcp/vault-operations/__tests__/vault-filesystem.test.ts1-210 cli/src/__tests__/init.test.ts1-137 cli/src/__tests__/lifecycle.test.ts1-208 src/vault-mcp/mcp-core/__tests__/prompt-test-harness.ts1-189
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.