# How to Run the Tests in Open Notebook: A Complete pytest and UV Guide > Learn how to run Open Notebook tests using pytest and UV. Execute the full pytest suite from the repository root with a simple command to validate core library, endpoints, workflows, and utilities. - Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook) - Tags: how-to-guide - Published: 2026-06-05 --- **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`](https://github.com/lfnovo/open-notebook/blob/main/tests/test_models_api.py), [`tests/test_graphs.py`](https://github.com/lfnovo/open-notebook/blob/main/tests/test_graphs.py), [`tests/test_embedding.py`](https://github.com/lfnovo/open-notebook/blob/main/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. ```bash 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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/README.dev.md) and executed in the GitHub Actions workflow defined in [`.github/workflows/test.yml`](https://github.com/lfnovo/open-notebook/blob/main/.github/workflows/test.yml). ```bash 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: ```bash 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. ```bash # 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`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/testing.md): ```bash 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`](https://github.com/lfnovo/open-notebook/blob/main/.github/workflows/test.yml)** — The GitHub Actions workflow that runs `uv run pytest tests/ -v` on every pull request. - **[`README.dev.md`](https://github.com/lfnovo/open-notebook/blob/main/README.dev.md)** — Developer guide that documents the canonical `uv run pytest tests/` command. - **[`docs/7-DEVELOPMENT/testing.md`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/README.dev.md) and executed by the GitHub Actions workflow in [`.github/workflows/test.yml`](https://github.com/lfnovo/open-notebook/blob/main/.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`](https://github.com/lfnovo/open-notebook/blob/main/tests/test_graphs.py), [`tests/test_embedding.py`](https://github.com/lfnovo/open-notebook/blob/main/tests/test_embedding.py)). The CI pipeline is defined in **[`.github/workflows/test.yml`](https://github.com/lfnovo/open-notebook/blob/main/.github/workflows/test.yml)**, and additional developer documentation is available in **[`docs/7-DEVELOPMENT/testing.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/testing.md)**.