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

> Easily run tests for the Semantica project with pytest. Install the package with test extras and execute pytest from the repository root for comprehensive testing.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-11

---

**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`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml) under `[project.optional-dependencies]`. The `test` extra includes **pytest**, **pytest-xdist** for parallel execution, and connectors for all optional vector-store backends.

```bash

# 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:

```bash
pytest

```

This command mirrors the behavior defined in [`.github/workflows/ci.yml`](https://github.com/semantica-agi/semantica/blob/main/.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:

```bash
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:

```bash
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:

```bash

# 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:

```bash

# 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:

```bash
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`](https://github.com/semantica-agi/semantica/blob/main/tests/vector_store/test_simple_end_to_end.py) | End-to-end vector-store workflow validation |
| [`tests/verify_backends.py`](https://github.com/semantica-agi/semantica/blob/main/tests/verify_backends.py) | Backend connectivity and availability verification |
| [`tests/visualization/test_visualization.py`](https://github.com/semantica-agi/semantica/blob/main/tests/visualization/test_visualization.py) | Interactive visualization component testing |
| [`tests/vector_store/test_performance_benchmarks.py`](https://github.com/semantica-agi/semantica/blob/main/tests/vector_store/test_performance_benchmarks.py) | Performance benchmarking suite |
| [`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml) | Source of truth for test dependencies and optional extras |
| [`.github/workflows/ci.yml`](https://github.com/semantica-agi/semantica/blob/main/.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:

```bash

# 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`](https://github.com/semantica-agi/semantica/blob/main/.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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/.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.