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

> Learn how to run tests for lfnovo/open-notebook using pytest. Install dev dependencies with uv sync and execute tests efficiently to ensure code quality.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: how-to-guide
- Published: 2026-06-26

---

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

```bash
pip install uv

```

Optionally, create a virtual environment to isolate dependencies:

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

```

## Installing Development Dependencies

The project declares testing tools in a dedicated `dev` group within [`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml) (lines 14-63). This group includes **pytest**, **pytest-asyncio**, **pytest-cov**, and other testing utilities.

Install all development dependencies using:

```bash
uv sync --group dev

```

This command reads the dependency specifications from [`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/testing.md) (lines 28-34) specify the standard command for executing the full suite:

```bash
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:**
  ```bash
  uv run pytest tests/test_models_api.py
  ```

- **Run a single test function:**
  ```bash
  uv run pytest tests/test_models_api.py::test_create_model
  ```

- **Run with verbose output and stop on first failure:**
  ```bash
  uv run pytest -vv -x
  ```

### Generating Coverage Reports

Measure code coverage for the `open_notebook` package:

```bash
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`](https://github.com/lfnovo/open-notebook/blob/main/tests/test_models_api.py) – API model validation
- [`tests/test_graphs.py`](https://github.com/lfnovo/open-notebook/blob/main/tests/test_graphs.py) – Graph processing logic
- [`tests/test_embedding.py`](https://github.com/lfnovo/open-notebook/blob/main/tests/test_embedding.py) – Embedding functionality
- [`tests/test_search_api.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml) (lines 14-63). Exact versions are pinned in `uv.lock` (lines 2180-2222), ensuring reproducible test environments across all contributors.