Testing Guide¶

Comprehensive testing documentation for ArcadeDB Python bindings.

Test Coverage

Current bindings suite

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

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:

Pattern 1: Embedded First → Server (requires manual close())
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¶

This is the current live test tree under bindings/python/tests. Exact test counts evolve, so this section lists files and responsibilities rather than hardcoding per-file totals.

tests/
├── conftest.py                         # Shared fixtures
├── test_async_executor.py             # Async execution tests
├── test_concurrency.py                # Concurrency tests
├── test_core.py                       # Core operations
├── test_cypher.py                     # OpenCypher tests
├── test_database_utils.py             # Database utility tests
├── test_docs_examples.py              # Runnable docs example tests
├── test_exporter.py                   # Exporter tests
├── test_geo_predicate_sql.py          # Geospatial SQL predicate tests
├── test_graph_algorithms_sql.py       # shortestPath / dijkstra / astar
├── test_graph_api.py                  # Graph API tests
├── test_graph_batch.py                # Bulk graph ingest helper
├── test_hash_index_schema.py          # HASH index schema tests
├── test_import_database.py            # SQL import workflow tests
├── test_importer_api.py               # Import helper wrapper tests
├── test_jvm_args.py                   # JVM argument tests
├── test_logging_helper.py             # Internal logging helper tests
├── test_materialized_view_sql.py      # Materialized view lifecycle
├── test_numpy_support.py              # NumPy integration tests
├── test_resultset.py                  # Result handling tests
├── test_schema.py                     # Schema tests
├── test_server.py                     # Server tests
├── test_server_patterns.py            # Embedded/server access patterns
├── test_timeseries_sql.py             # Timeseries SQL coverage
├── test_transaction_config.py         # Transaction config tests
├── test_type_conversion.py            # Type conversion tests
├── test_vector.py                     # Vector API tests
├── test_vector_params_verification.py # Vector parameter validation tests
├── test_vector_sql.py                 # Vector SQL tests
└── test_wheel_platform_tag.py         # Wheel platform tag tests

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