Testing Guide

Comprehensive testing documentation for ArcadeDB Python bindings.

Test Coverage

Current bindings suite

• Current package: 290 passed
• All ArcadeDB features working (SQL, OpenCypher, Studio)

Quick Navigation

• Overview

  ---

  Quick start, statistics, and how to run tests

• Core Tests

  ---

  CRUD, transactions, queries, graph operations (13 tests)

• Server Tests

  ---

  HTTP API, Studio, configuration

• Concurrency Tests

  ---

  File locking, thread safety, multi-process

• Server Patterns

  ---

  Embedded + HTTP best practices

• Data Import Tests

  ---

  SQL IMPORT DATABASE workflows and format coverage

• Docs Example Tests

  ---

  Executable coverage for representative Python snippets in the MkDocs docs tree

• GraphBatch Tests

  ---

  Engine-backed bulk graph ingest helper coverage

• Geo Predicate SQL Tests

  ---

  SQL geo.within and geo.intersects semantics

• Timeseries SQL Tests

  ---

  SQL-first timeseries type creation, range queries, and bucketing

• Materialized View SQL Tests

  ---

  Materialized view lifecycle, refresh, and metadata coverage

• Graph Algorithms SQL Tests

  ---

  shortestPath, dijkstra, and astar runtime coverage

• Hash Index Schema Tests

  ---

  HASH index creation, discovery, and drop coverage

• OpenCypher Tests

  ---

  Graph traversal language

• Best Practices

  ---

  Summary of recommended patterns and practices

Quick Start

Installation

# Install test dependencies
uv pip install pytest pytest-cov

Running Tests

# Run all tests
pytest

# Run specific category
pytest tests/test_core.py -v
pytest tests/test_concurrency.py -v

# Run with coverage
pytest --cov=arcadedb_embedded --cov-report=html

Test Coverage Summary

Category	What's Tested
Core Operations	CRUD, transactions, queries, graph operations, vector search
Server Mode	HTTP API, Studio UI, configuration, multiple databases
Concurrency	File locking, thread safety, multi-process limitations
Server Patterns	Embedded+HTTP combinations, lock management
Data Import	SQL import workflows, type inference, batch commits
Query Languages	SQL, OpenCypher
Advanced Features	Unicode support, schema introspection, geospatial SQL, timeseries SQL, graph algorithms, materialized views, HASH indexes

Key Concepts

Concurrency Model

Can multiple Python instances access the same database?

• ❌ Multiple processes cannot (file lock prevents it)
• ✅ Multiple threads can (thread-safe within same process)
• ✅ Use server mode for true multi-process access

See Concurrency Tests for details.

Server Access Patterns

Two ways to combine embedded + HTTP access:

1. Pattern 1: Embedded First → Server (requires manual close())
2. Pattern 2: Server First → Create (recommended, simpler)

See Server Patterns for detailed comparison.

Performance Insight

No HTTP Overhead

Embedded access through server is just as fast as standalone embedded mode!

It's a direct JVM call, not HTTP. Same Python process = zero network overhead.

Common Testing Workflows

Development

# Run tests matching keyword
pytest -k "transaction" -v
pytest -k "import" -v

# Stop on first failure
pytest -x

# Drop into debugger on failure
pytest --pdb

# Show skipped test reasons
pytest -v -rs

Test Organization

tests/
├── test_core.py              # Core operations (13 tests)
├── test_server.py            # Server mode (6 tests)
├── test_concurrency.py       # Concurrency (4 tests)
├── test_server_patterns.py   # Patterns (4 tests)
├── test_graph_batch.py       # Bulk graph ingest helper
├── test_graph_algorithms_sql.py  # shortestPath / dijkstra / astar
├── test_geo_predicate_sql.py # Geospatial SQL predicates
├── test_timeseries_sql.py    # Timeseries SQL coverage
├── test_materialized_view_sql.py # Materialized view lifecycle
├── test_hash_index_schema.py # HASH index schema API coverage
├── test_import_database.py   # Import database tests
├── test_docs_examples.py     # Validates runnable docs examples
├── test_cypher.py            # OpenCypher (tests)
└── conftest.py               # Shared fixtures

Next Steps

New to testing? Start with Overview

Working with databases? See Core Tests

Need multi-process access? Read Concurrency Tests

Setting up a server? Check Server Patterns

Importing data? See Data Import Tests

Checking docs examples? See Docs Example Tests

Want best practices? Read Best Practices Summary