How to Run the Tests in Open Notebook: A Complete pytest and UV Guide

Use uv run pytest tests/ from the repository root to execute the full pytest suite that validates the core library, FastAPI endpoints, LangGraph workflows, and content-processing utilities.

Open Notebook ships with a comprehensive pytest-based test suite that validates the core Python library, the FastAPI endpoints, the LangGraph workflows, and the content-processing utilities. Learning how to run the tests is straightforward because the project uses UV as its Python package manager, ensuring the correct virtual environment and dependency versions are loaded automatically. The tests live under the top-level tests/ directory (e.g., tests/test_models_api.py, tests/test_graphs.py, tests/test_embedding.py) and are executed with simple commands referenced in the developer guide and CI configuration.

Prerequisites for Running the Tests

Before executing the suite, clone the repository and install dependencies via UV.

git clone https://github.com/lfnovo/open-notebook.git
cd open-notebook
cp .env.example .env
uv sync

The .env file is required because the test suite relies on environment variables defined in README.dev.md. The uv sync command installs all locked dependencies into the project-specific virtual environment.

Run the Full Test Suite

The canonical way to run the tests is with the uv run pytest tests/ command. This method is explicitly referenced in README.dev.md and executed in the GitHub Actions workflow defined in .github/workflows/test.yml.

uv run pytest tests/

For verbose output, the CI pipeline runs uv run pytest tests/ -v. You can replicate this locally to see individual test names and pass/fail status in real time.

Alternatively, use the Makefile target that wraps the same command for consistency between local development and CI:

make test

The Makefile provides a single entry point for developers and is implicitly used by the GitHub workflow to guarantee identical behavior across environments.

Run Selective Tests and Coverage Reports

When debugging a failing module, you can target specific files, classes, or functions instead of the entire suite.

# Run a single test module

uv run pytest tests/test_models_api.py

# Run a specific test class

uv run pytest tests/test_models_api.py::TestCreateModel

# Run a specific test function

uv run pytest tests/test_models_api.py::test_create_model

Pytest automatically discovers any file named test_*.py or *_test.py, so adding new tests under tests/ requires no extra configuration changes.

To assess test completeness, generate a coverage report with the --cov flag as recommended in docs/7-DEVELOPMENT/testing.md:

uv run pytest --cov=open_notebook tests/

This reports line coverage for the open_notebook package and helps identify untested code paths in the core library.

Why UV Is Required for Testing

UV guarantees the same interpreter—Python 3.11+—and isolates the test environment from any global Python installation. Because uv run automatically selects the project virtual environment, you avoid dependency conflicts that often break pytest discovery or cause import errors in FastAPI and LangGraph modules.

Key Files for Test Configuration

Understanding the repository layout makes it easier to extend or debug the suite.

• tests/ — Contains the full pytest suite covering domain logic, API endpoints, and graph layers.
• Makefile — Defines the test target used by CI and local developers, plus helpers like make ruff and make lint.
• .github/workflows/test.yml — The GitHub Actions workflow that runs uv run pytest tests/ -v on every pull request.
• README.dev.md — Developer guide that documents the canonical uv run pytest tests/ command.
• docs/7-DEVELOPMENT/testing.md — Detailed testing instructions, including async pytest usage and coverage recommendations.

If you only need to lint the code without executing tests, run make ruff or make lint before committing changes.

Summary

• Execute the full suite with uv run pytest tests/, the canonical command documented in README.dev.md.
• Use make test to mirror the exact target used by the GitHub Actions CI workflow.
• Target individual files or classes by appending the path and optional :: selector to the pytest command.
• Generate coverage reports with --cov=open_notebook as recommended in docs/7-DEVELOPMENT/testing.md.
• Rely on UV to enforce Python 3.11+ and isolate dependencies automatically.

Frequently Asked Questions

What command runs the full Open Notebook test suite?

Run uv run pytest tests/ from the repository root. This command is the canonical method referenced in README.dev.md and executed by the GitHub Actions workflow in .github/workflows/test.yml.

How do I run only one specific test file or test case?

Append the relative file path to the pytest command, or narrow it further with the :: syntax. For example, uv run pytest tests/test_models_api.py::TestCreateModel runs only that specific class, while uv run pytest tests/test_models_api.py runs the entire module.

Does Open Notebook require a virtual environment to run tests?

No manual virtual environment setup is required. The UV package manager handles isolation automatically when you invoke uv run, ensuring the correct Python 3.11+ interpreter and locked dependencies are loaded for every test run.

Where are the test suite and CI configuration files located?

The tests reside in the top-level tests/ directory (e.g., tests/test_graphs.py, tests/test_embedding.py). The CI pipeline is defined in .github/workflows/test.yml, and additional developer documentation is available in docs/7-DEVELOPMENT/testing.md.

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