Test Coverage & Automation

Relevant source files

The following files were used as context for generating this wiki page:

• apps/frontend/src/api.test.ts
• tests/api/test_system.py
• archivum-prd-v1.0.md
• README.md
• apps/backend/archivum/mcp/server.py
• apps/backend/archivum/mcp/demo.py

The Archivum testing and automation strategy ensures the reliability of a complex, AI-powered knowledge base through multi-layered validation. The scope of testing covers backend REST APIs, Model Context Protocol (MCP) tool definitions, frontend API client logic, and system-level maintenance operations such as index rebuilding and wiki linting.

Testing is distributed across unit tests for individual components, integration tests for API endpoints, and automated validation via GitHub Actions. A key objective is validating the "Self-hosted wiki that organizes itself" loop, ensuring that ingestion, extraction, and search function correctly across different transport layers and data providers.

Sources: README.md:3-9, archivum-prd-v1.0.md:13, tests/api/test_system.py:1-4

Backend API & System Testing

The backend is tested using Python's unittest framework and FastAPI.testclient. These tests focus on core system health, indexing reliability, and maintenance tools.

System Maintenance Validation

The system tests verify the functionality of critical maintenance endpoints. This includes the audio support check, index rebuilding, and the wiki linting engine. The linting engine specifically identifies broken wikilinks, orphan pages (pages with no incoming or outgoing links), and contradictory claims between pages.

Category	Endpoint	Test Objective
System	/api/audio-support	Verify dependency availability for transcription.
Indexing	/api/rebuild-indexes	Ensure derived indexes (Qdrant/Kuzu) are fully reconstructible.
Linting	/api/lint	Detect broken wikilinks, orphans, and contradictory claims.
Correction	/api/lint/fix	Validate automatic patching of content for specific issues.

Sources: tests/api/test_system.py:32-151, archivum-prd-v1.0.md:6

Authentication & Request Security

API tests utilize a _make_client helper to simulate different security contexts. This allows for testing both Cookie-based authentication for the web UI and Bearer-based authentication for MCP clients or CLI tools. Tests specifically verify that Bearer tokens successfully bypass CSRF middleware for mutating operations like POST and PUT.

Sources: tests/api/test_system.py:17-26, apps/frontend/src/api.test.ts:98-111

MCP Server Validation

Archivum implements a robust validation strategy for its MCP server to ensure compatibility across various AI clients like Claude Desktop and Cursor.

Transport & Schema Validation

The MCP server supports both stdio and HTTP/SSE transports. Verification is performed using the MCP Inspector tool, which validates that tool schemas are compliant with the protocol.

Automated checks verify the following MCP tools:

• ingest_source: Processing files/URLs.
• search_wiki: Semantic retrieval.
• query: LLM-powered synthesis with citations.
• lint_wiki: Wiki health reporting.

Sources: README.md:179-195, apps/backend/archivum/mcp/server.py:276-285, archivum-prd-v1.0.md:9

Mock-based Demo Validation

For environments without a full infrastructure stack (Qdrant, Neo4j/Kuzu), the project includes a standalone demo module (demo.py). This module uses mock data to exercise all MCP tools, generating an inspectable artifact report in HTML and JSON. This serves as a "smoke test" for the interface logic without requiring active database connections.

Sources: apps/backend/archivum/mcp/demo.py:10-18, README.md:231-238

Frontend API Client Testing

The frontend utilizes vitest to ensure the API client accurately communicates with the backend services.

API Client Mocking

Frontend tests extensively use vi.fn() and vi.stubGlobal to mock the global fetch API. This isolates the client-side logic for:

• Session Management: Refreshing tokens and managing login/logout states.
• CRUD Operations: Creating, updating, and moving pages and folders.
• Life OS Workflows: Creating daily notes and project tasks.

CSRF & Header Verification

A critical part of frontend testing is ensuring that security headers are correctly appended to requests. Tests verify that if a csrf_token cookie is present, the corresponding X-CSRF-Token header is included in the outgoing fetch request.

it('sends CSRF token when cookie present', async () => {
  vi.stubGlobal('document', { cookie: 'csrf_token=test-csrf-token' });
  // ... test implementation ...
  expect(fetchMock).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
    headers: expect.objectContaining({ 'X-CSRF-Token': 'test-csrf-token' }),
  }));
});

Sources: apps/frontend/src/api.test.ts:13-30, apps/frontend/src/api.test.ts:113-127, apps/frontend/src/api.test.ts:241-260

Automation & CI/CD

Automation is primarily handled via GitHub Actions and localized shell scripts.

Continuous Integration

The repository includes a GitHub Actions workflow (.github/workflows/docker-publish.yml) that triggers on pushes to the main branch or specific tags. This workflow performs:

1. Code Validation: Running tests and linting.
2. Multi-arch Builds: Building Docker images for linux/amd64 and linux/arm64.
3. Image Publishing: Pushing validated images to the GitHub Container Registry.

Sources: README.md:144-152

Local Setup & Smoke Tests

For local developer environments, a make setup command and a bootstrap.sh script automate the initialization of the stack. A make mcp-smoke command is specifically used to confirm that the MCP server exposes the expected tools after a boot.

Sources: README.md:27-35, Progress.md:20

Archivum's Test Coverage & Automation architecture ensures that the knowledge base remains a reliable "Memex" for the user, where data integrity is maintained through rigorous validation of the ingestion pipeline and derived indexes.