How to Run Tests for lfnovo/open-notebook: A Complete pytest Guide

Run tests for lfnovo/open-notebook by installing development dependencies with uv sync --group dev and executing uv run pytest from the project root.

The open-notebook repository relies on pytest with async support to validate its Python codebase. To run tests for lfnovo/open-notebook, you must use the uv package manager to install development dependencies and execute the test suite located in the tests/ directory.

Prerequisites: Python and uv Installation

Before running tests, ensure your environment meets the project's toolchain requirements.

Open-notebook requires Python 3.11 or Python 3.12. Install the uv package manager, which is the recommended tool for dependency management:

pip install uv

Optionally, create a virtual environment to isolate dependencies:

uv venv .venv && source .venv/bin/activate

Installing Development Dependencies

The project declares testing tools in a dedicated dev group within pyproject.toml (lines 14-63). This group includes pytest, pytest-asyncio, pytest-cov, and other testing utilities.

Install all development dependencies using:

uv sync --group dev

This command reads the dependency specifications from pyproject.toml and locks exact versions in uv.lock (lines 2180-2222), ensuring reproducible test environments.

Running the Test Suite

The official testing instructions in docs/7-DEVELOPMENT/testing.md (lines 28-34) specify the standard command for executing the full suite:

uv run pytest

This discovers and runs all tests under the tests/ directory, including unit tests, integration tests, and graph validation tests.

Running Specific Tests

Target individual test files or functions to speed up debugging:

• Run a specific test file:

  uv run pytest tests/test_models_api.py

• Run a single test function:

  uv run pytest tests/test_models_api.py::test_create_model

• Run with verbose output and stop on first failure:

  uv run pytest -vv -x

Generating Coverage Reports

Measure code coverage for the open_notebook package:

uv run pytest --cov=open_notebook

Understanding the Test Structure

The test suite is organized under the tests/ directory with specific files validating different components:

• tests/test_models_api.py – API model validation
• tests/test_graphs.py – Graph processing logic
• tests/test_embedding.py – Embedding functionality
• tests/test_search_api.py – Search capabilities

All files follow the test_*.py naming convention required by pytest discovery.

Summary

• Install uv and Python 3.11/3.12 to prepare the environment.
• Sync dependencies using uv sync --group dev to install pytest and plugins.
• Execute tests with uv run pytest to run the full suite under tests/.
• Target specific tests by passing file paths or function names to pytest.
• Generate coverage using the --cov=open_notebook flag to analyze test completeness.

Frequently Asked Questions

What Python version is required to run tests for lfnovo/open-notebook?

The project requires Python 3.11 or Python 3.12 to execute the test suite correctly. Ensure your environment matches one of these versions before installing dependencies to avoid compatibility issues with the async test patterns used throughout the codebase.

Why does the project use uv instead of pip for testing?

Open-notebook recommends uv as its Python package manager because it provides significantly faster dependency resolution and installation compared to pip. The testing workflow relies on uv sync and uv run commands to ensure consistent environments across development machines, as documented in the project's testing guide.

How do I run only specific tests instead of the entire suite?

You can target specific test files by passing the file path to pytest, such as uv run pytest tests/test_models_api.py. To run individual test functions, use the double-colon syntax: uv run pytest tests/test_models_api.py::test_create_model.

Where are the test dependencies and configuration defined?

The test dependencies—including pytest, pytest-asyncio, and pytest-cov—are declared in the dev group of pyproject.toml (lines 14-63). Exact versions are pinned in uv.lock (lines 2180-2222), ensuring reproducible test environments across all contributors.

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