How to Run Tests for the Semantica Project: A Complete pytest Guide

Run Semantica's test suite by installing the package with test extras (pip install -e .[test]) and executing pytest from the repository root.

The Semantica project is an open-source semantic AI library that uses pytest as its testing framework. All tests reside in the top-level tests/ directory, with comprehensive coverage for vector stores, backends, and visualization components. This guide walks through installation, execution strategies, and CI-aligned workflows based on the actual source code structure.

Installing Test Dependencies

Semantica declares its test dependencies in pyproject.toml under [project.optional-dependencies]. The test extra includes pytest, pytest-xdist for parallel execution, and connectors for all optional vector-store backends.

# Clone the repository

git clone https://github.com/semantica-agi/semantica.git
cd semantica

# Install in editable mode with test dependencies

pip install -e .[test]

This single command installs pytest and every optional backend driver: FAISS, Qdrant, Weaviate, Milvus, Pinecone, PgVector, and others. Tests for unavailable backends are automatically skipped using pytest.importorskip or pytest.mark.skipif.

Running the Full Test Suite

Execute all tests from the repository root:

pytest

This command mirrors the behavior defined in .github/workflows/ci.yml, which runs on every push. By default, the suite includes integration tests marked with @pytest.mark.integration.

To exclude slower integration tests:

pytest -m "not integration"

Parallel Execution with pytest-xdist

The tests/ directory contains numerous independent modules, particularly vector-store benchmarks. Speed up execution using the included pytest-xdist plugin:

pytest -n auto

The -n auto flag automatically detects available CPU cores and distributes tests across them.

Running Specific Tests

Target individual files, classes, or functions for faster debugging:

# Run a single test file

pytest tests/vector_store/test_simple_end_to_end.py

# Run a specific test function

pytest tests/vector_store/test_faiss_index.py::test_faiss_import

# Run all vector-store tests

pytest tests/vector_store/

Enabling Optional Backend Tests

Tests for specific backends auto-skip if dependencies are missing. Enable them by installing the corresponding extra:

# Enable FAISS tests

pip install "semantica[faiss]"
pytest tests/vector_store/test_faiss_index.py

# Enable Pinecone tests

pip install "semantica[pinecone]"

Verify your environment setup using the dedicated backend checker:

python tests/verify_backends.py

Key Test Files and Their Purpose

File	Purpose
tests/	Root directory containing unit, integration, and performance tests
tests/vector_store/test_simple_end_to_end.py	End-to-end vector-store workflow validation
tests/verify_backends.py	Backend connectivity and availability verification
tests/visualization/test_visualization.py	Interactive visualization component testing
tests/vector_store/test_performance_benchmarks.py	Performance benchmarking suite
pyproject.toml	Source of truth for test dependencies and optional extras
.github/workflows/ci.yml	CI configuration that validates the pytest command

Environment Verification Workflow

Before contributing, run this sequence to confirm your setup matches CI expectations:

# 1. Install with all test dependencies

pip install -e .[test]

# 2. Verify backend availability

python tests/verify_backends.py

# 3. Run fast unit tests only

pytest -m "not integration" -n auto

# 4. Run full suite including integrations

pytest

Summary

• Install: Use pip install -e .[test] to get pytest and all optional dependencies
• Execute: Run pytest from the repository root; matches .github/workflows/ci.yml
• Accelerate: Add -n auto for parallel execution, -m "not integration" to skip slow tests
• Target: Specify files or functions with pytest path/to/file.py::test_function
• Verify: Use tests/verify_backends.py to check environment readiness

Frequently Asked Questions

What testing framework does Semantica use?

Semantica uses pytest as its primary testing framework. The test suite is organized under the tests/ directory with subdirectories for different components like vector_store/ and visualization/. Configuration and dependencies are defined in pyproject.toml.

How do I run tests without installing all optional backends?

Install only the core test dependencies, then run with markers to skip backend-specific tests. Tests automatically skip when their required dependencies are missing. Use pytest -m "not integration" for the fastest execution without heavy external services.

Where is the CI configuration for Semantica tests?

The CI workflow lives at .github/workflows/ci.yml. It runs pytest on every push and pull request, ensuring local test commands align with automated validation. The badge in the README reflects this workflow's status.

How can I verify my environment is correctly configured?

Run python tests/verify_backends.py to check which optional backends are available. This script validates that your environment matches the requirements for running the full test suite, including external vector store connections.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}