OpenViking/tests/README.md

OpenViking Tests

Unit tests and integration tests for OpenViking.

Directory Structure

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_http_client_config.py -v

# Run a specific test class
pytest tests/client/test_http_client_config.py::test_async_http_client_explicit_values_override_ovcli_config -v

# Run a specific test function
pytest tests/client/test_http_client_config.py -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_http_client_config.py -v -s

Common Test Scenarios

# Test HTTP client configuration
pytest tests/client/test_http_client_config.py -v

# Test resource add and processing
pytest tests/server/test_api_resources.py -v

# Test skill management
pytest tests/server/test_api_skills.py -v

# Test semantic search
pytest tests/server/test_api_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 Python HTTP client API.

File	Description	Key Test Cases
test_http_client_config.py	Connection and identity configuration	URL, API key, headers, timeout, and compatibility behavior
test_http_client_local_upload.py	Local uploads	File and directory upload behavior
test_http_client_snapshot.py	Snapshot operations	Snapshot namespace and response handling
test_http_error_mapping.py	Error mapping	Server, network, timeout, and conflict errors
test_rebuild_clients.py	Reindex and message operations	Async and sync HTTP request forwarding

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_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