tests/
├── conftest.py                      # Global fixtures
├── client/                          # Client API tests
├── server/                          # Server HTTP API & SDK tests
├── session/                         # Session API tests
├── vectordb/                        # VectorDB tests
├── misc/                            # Miscellaneous tests
├── engine/                          # C++ engine tests
└── integration/                     # End-to-end workflow tests

Prerequisites

Configuration

Set the OPENVIKING_CONFIG_FILE environment variable to point to your ov.conf file, which manages VLM, Embedding, and other model settings in one place:

export OPENVIKING_CONFIG_FILE="/path/to/ov.conf"

See docs/en/guides/configuration.md for the config file format.

Dependencies

pip install pytest pytest-asyncio pytest-cov

Running Tests

Python Tests

# Run all tests
pytest tests/client tests/server tests/session tests/vectordb tests/misc tests/integration -v

# Run with coverage
pytest tests/client tests/server tests/session tests/vectordb tests/misc tests/integration -v --cov=openviking --cov-report=term-missing

Running Specific Tests

# Run a specific test module
pytest tests/client/test_lifecycle.py -v

# Run a specific test class
pytest tests/client/test_lifecycle.py::TestClientInitialization -v

# Run a specific test function
pytest tests/client/test_lifecycle.py::TestClientInitialization::test_initialize_success -v

# Run tests matching a keyword
pytest tests/ -k "lifecycle" -v
pytest tests/ -k "initialize" -v

# Run tests with print output visible
pytest tests/client/test_lifecycle.py -v -s

Common Test Scenarios

# Test client lifecycle (init, close, reset)
pytest tests/client/test_lifecycle.py -v

# Test resource add and processing
pytest tests/client/test_resource_management.py -v

# Test skill management
pytest tests/client/test_skill_management.py -v

# Test semantic search
pytest tests/client/test_search.py -v

# Test server HTTP API
pytest tests/server/ -v

# Test server SDK end-to-end
pytest tests/server/test_http_client_sdk.py -v

# Test session management
pytest tests/session/ -v

# Test vector database operations
pytest tests/vectordb/ -v

# Test full end-to-end workflow
pytest tests/integration/test_full_workflow.py -v

C++ Engine Tests

cd tests/engine
mkdir build && cd build
cmake ..
make
./test_index_engine

Test Modules

client/

Tests for the OpenViking client API (AsyncOpenViking / SyncOpenViking).

File	Description	Key Test Cases
`test_lifecycle.py`	Client lifecycle management	`initialize()` success and idempotency, `close()` cleanup, `reset()` singleton clearing, embedded mode singleton behavior
`test_resource_management.py`	Resource operations	`add_resource()` with sync/async modes, custom target URI, file not found handling; `wait_processed()` for single and batch resources
`test_skill_management.py`	Skill operations	`add_skill()` from SKILL.md file, YAML string, MCP tool dict, skill directory with auxiliary files; skill search
`test_filesystem.py`	Virtual filesystem	`ls()` with simple/recursive modes; `read()` file content; `abstract()` L0 summary; `overview()` L1 overview; `tree()` directory structure
`test_search.py`	Semantic search	`find()` fast vector search with limit/threshold/target_uri; `search()` with intent analysis and session context
`test_relations.py`	Resource linking	`link()` single/multiple URIs with reason; `unlink()` existing/nonexistent; `relations()` query
`test_file_operations.py`	File manipulation	`rm()` file/directory with recursive; `mv()` rename/move; `grep()` content search with case sensitivity; `glob()` pattern matching
`test_import_export.py`	Import/Export	`export_ovpack()` file/directory; `import_ovpack()` with conflict policy; roundtrip verification

server/

Tests for the OpenViking HTTP server API and AsyncHTTPClient SDK.

File	Description	Key Test Cases
`test_server_health.py`	Server infrastructure	`/health` endpoint, `/api/v1/system/status`, `x-process-time` header, structured error responses, 404 for unknown routes
`test_auth.py`	API key authentication	Valid X-API-Key header, valid Bearer token, missing/wrong key returns 401, no auth when API key not configured, protected endpoints
`test_api_resources.py`	Resource management	`add_resource()` with/without wait, file not found, custom target URI, `wait_processed()`
`test_api_filesystem.py`	Filesystem endpoints	`ls` root/simple/recursive, `mkdir`, `tree`, `stat`, `rm`, `mv`
`test_api_content.py`	Content endpoints	`read`, `abstract`, `overview`
`test_api_search.py`	Search endpoints	`find` with target_uri/score_threshold, `search` with session, `grep` case-insensitive, `glob`
`test_api_sessions.py`	Session endpoints	Create, list, get, delete session; add messages; compress; extract
`test_api_relations.py`	Relations endpoints	Get relations, link single/multiple targets, unlink
`test_api_observer.py`	Observer endpoints	Queue, VikingDB, VLM, system observer status
`test_error_scenarios.py`	Error handling	Invalid JSON, missing fields, not found, wrong content type, invalid URI format
`test_http_client_sdk.py`	AsyncHTTPClient SDK E2E	Health, add resource, wait, ls, mkdir, tree, session lifecycle, find, full workflow (real HTTP server)

session/

Tests for session management (Session class).

File	Description	Key Test Cases
`test_session_lifecycle.py`	Session creation and persistence	Create new session, create with custom ID, multiple sessions; `load()` existing session, load nonexistent
`test_session_messages.py`	Message management	`add_message()` user/assistant roles, TextPart/ContextPart/ToolPart
`test_session_usage.py`	Usage tracking	`used()` record context URIs, record skill usage, record both; multiple usage records per session
`test_session_commit.py`	Session commit	`commit()` success status, memory extraction trigger, message archiving, empty session handling, multiple commits, usage record persistence
`test_session_context.py`	Context for search	`get_context_for_search()` with `current_messages` + `latest_archive_overview`; latest completed archive only

vectordb/

Tests for the vector database layer (VikingVectorIndex).

File	Description	Key Test Cases
`test_bytes_row.py`	Binary row storage	Row serialization/deserialization, binary data handling
`test_collection_large_scale.py`	Large scale operations	Collection creation with many vectors, batch insert performance, query latency at scale
`test_crash_recovery.py`	Crash recovery	WAL replay, index reconstruction, data integrity after crash
`test_filter_ops.py`	Filter operations	Metadata filtering (eq, ne, gt, lt, in, contains), compound filters, filter with vector search
`test_project_group.py`	Project/group management	Project isolation, group operations, cross-project queries
`test_pydantic_validation.py`	Data validation	Schema validation, type coercion, validation error handling
`reproduce_bugs.py`	Bug reproduction	Scripts for reproducing and verifying bug fixes

misc/

Miscellaneous tests.

File	Description	Key Test Cases
`test_vikingdb_observer.py`	Database observer	State change notifications, observer registration/unregistration, event filtering
`test_code_parser.py`	Code repository parser	`ignore_dirs` compliance, `ignore_extensions` compliance, file type detection, symbolic link handling
`test_config_validation.py`	Configuration validation	Config schema validation, required fields, type checking
`test_debug_service.py`	Debug service	Debug endpoint tests, service diagnostics
`test_extract_zip.py`	Zip extraction security (Zip Slip)	Path traversal prevention (`../`), absolute path rejection, symlink entry filtering, backslash traversal, UNC path rejection, directory entry skipping, normal extraction
`test_mkdir.py`	VikingFS.mkdir() fix verification	mkdir calls agfs.mkdir, exist_ok=True skips existing, exist_ok=True creates missing, default creation, parent-before-target ordering
`test_port_check.py`	AGFS port check socket leak fix	Available port no leak, occupied port raises RuntimeError, occupied port no ResourceWarning

engine/

C++ tests for the index engine (GoogleTest).

File	Description	Key Test Cases
`test_common.cpp`	Common utilities	Memory management, string operations, error handling
`test_index_engine.cpp`	Index engine	Vector indexing, similarity search, index persistence, concurrent access

integration/

End-to-end workflow tests.

File	Description	Key Test Cases
`test_full_workflow.py`	Complete workflows	Resource→vectorize→search flow; Session conversation→commit→memory extraction; Export→delete→import roundtrip; Full E2E with all components