# How to Run Tests for Open-Notebook: A Complete pytest and uv Guide

> Learn how to run tests for Open-Notebook using pytest and uv. Follow this guide to set up your environment and execute the test suite efficiently.

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

---

**Run the full Open-Notebook test suite with `uv run pytest` after installing dev dependencies via `uv sync --dev`; the project uses pytest with asyncio support and organizes tests under `tests/`.**

The `lfnovo/open-notebook` repository relies on **pytest** and **pytest-asyncio** to validate its async Python codebase. If you are contributing or deploying the project, knowing **how to run tests for open-notebook** ensures that changes to the FastAPI backend, SurrealDB queries, or domain logic do not break existing functionality. All test commands execute from the repository root and require Python 3.11+ with the `uv` package manager.

## Prerequisites: Python 3.11 and uv

Before executing any tests, verify that your environment meets the requirements defined in [`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml). The project specifies Python 3.11 or newer and uses `uv` as its preferred package manager.

Install the development dependencies from the repository root:

```bash
uv sync --dev

```

This command reads [`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml) and installs **pytest**, **pytest-asyncio**, and the remaining dev dependencies required by the test suite.

## Essential Commands to Run the Open-Notebook Test Suite

All commands below assume you are executing from the repository root. The `uv run` prefix ensures that pytest runs inside the project's managed environment.

Run the entire test suite:

```bash
uv run pytest

```

Run a single test file, such as the models API tests:

```bash
uv run pytest tests/test_models_api.py

```

Run a single test function by its fully qualified name:

```bash
uv run pytest tests/test_models_api.py::test_create_notebook

```

Run only the unit tests:

```bash
uv run pytest tests/unit/

```

Generate a coverage report for the `open_notebook` package:

```bash
uv run pytest --cov=open_notebook

```

Enable verbose output or show printed statements:

```bash
uv run pytest -v
uv run pytest -s

```

## How the Open-Notebook Test Suite Is Organized

Understanding the directory structure helps you target the right tests during development.

### Framework and Async Support

According to the `lfnovo/open-notebook` source code, [`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml) declares **pytest** and **pytest-asyncio** as development dependencies. Because most of the production code is asynchronous, the test suite uses `@pytest.mark.asyncio` to wrap async functions and `await` to invoke coroutines directly inside test cases.

### Test Directory Layout

The `tests/` directory splits validation into four categories:

- **Unit tests** (`tests/unit/`): Validate pure business logic such as domain model validation, repository helpers, and utility functions.
- **Integration tests** (`tests/integration/`): Spin up the FastAPI app with an `httpx.AsyncClient` and a real SurrealDB instance to verify end-to-end flows like notebook creation with source linking.
- **API tests** (`tests/api/`): Directly exercise the FastAPI routers in `api/routers/*.py`, asserting HTTP status codes, response payloads, and error handling.
- **Database tests** (`tests/database/`): Isolate SurrealDB queries, migrations, and vector-search functionality.

### Shared Fixtures in conftest.py

Common setup and teardown logic live in [`tests/conftest.py`](https://github.com/lfnovo/open-notebook/blob/main/tests/conftest.py). Key fixtures such as `api_client` and `test_notebook` provide a clean async environment, populate temporary data, and clean up after each test. Any module inside `tests/` can import these fixtures automatically.

### Async Test Patterns

Tests mirror the production code’s async design. For example, in [`tests/test_models_api.py`](https://github.com/lfnovo/open-notebook/blob/main/tests/test_models_api.py) (lines 18-20), functions are decorated with `@pytest.mark.asyncio` and use `await` on all async calls. This pattern keeps the test suite consistent with the async runtime used by the FastAPI application entry point in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py).

## Code Examples for Running Open-Notebook Tests

### Running a Specific API Test

The following example from the API test suite creates a notebook through the FastAPI application using `httpx.AsyncClient`:

```python

# tests/api/test_notebooks_api.py

import pytest
from httpx import AsyncClient
from api.main import app  # FastAPI instance

@pytest.mark.asyncio
async def test_create_notebook_via_api():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.post(
            "/api/notebooks",
            json={"name": "My Notebook", "description": "Demo"},
        )
        assert response.status_code == 200
        data = response.json()
        assert data["name"] == "My Notebook"

```

Execute that individual test with:

```bash
uv run pytest tests/api/test_notebooks_api.py::test_create_notebook_via_api

```

### Using a Reusable Notebook Fixture

The [`tests/conftest.py`](https://github.com/lfnovo/open-notebook/blob/main/tests/conftest.py) file defines an async `test_notebook` fixture that creates a temporary notebook and removes it after the test:

```python

# tests/conftest.py

import pytest
from open_notebook.domain.notebook import Notebook

@pytest.fixture
async def test_notebook():
    nb = Notebook(name="Temp Notebook", description="Temp")
    await nb.save()
    yield nb
    await nb.delete()

```

Any test function can request this fixture to receive a fresh notebook instance without duplicating setup logic.

## Where to Find Testing Configuration

Several files govern how tests behave and what standards they must meet:

- **[`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml)** — Declares `pytest`, `pytest-asyncio`, and other dev dependencies. It also pins the minimum Python version.
- **[`docs/7-DEVELOPMENT/testing.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/testing.md)** — Documents the official testing guide, including best practices and the project's coverage goals: 70%+ overall and 90%+ for critical business logic.
- **[`tests/conftest.py`](https://github.com/lfnovo/open-notebook/blob/main/tests/conftest.py)** — Houses shared fixtures for async setup and teardown across the suite.
- **[`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py)** — Provides the FastAPI application entry point imported by API and integration tests.
- **`open_notebook/domain/`** — Contains the core business-logic modules exercised by unit tests.

## Summary

- **How to run tests for open-notebook:** Use `uv run pytest` from the repository root after running `uv sync --dev`.
- The suite is organized into `tests/unit/`, `tests/integration/`, `tests/api/`, and `tests/database/` to separate concerns.
- [`tests/conftest.py`](https://github.com/lfnovo/open-notebook/blob/main/tests/conftest.py) supplies shared async fixtures such as `test_notebook` and `api_client`.
- All async tests rely on `pytest-asyncio` and the `@pytest.mark.asyncio` decorator.
- Target coverage is 70%+ overall and 90%+ for critical paths, as documented in [`docs/7-DEVELOPMENT/testing.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/testing.md).

## Frequently Asked Questions

### What is the minimum Python version required to run tests for open-notebook?

The project requires Python 3.11 or newer, which is enforced in [`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml). You must use this version or higher to ensure compatibility with the async syntax and dependency resolution used by the test suite.

### How do I run only the unit tests in open-notebook?

Execute `uv run pytest tests/unit/` from the repository root. This targets only the pure business-logic tests and skips the heavier integration, API, and database tests that require external services like SurrealDB.

### Why do open-notebook tests require pytest-asyncio?

Because the majority of the `lfnovo/open-notebook` codebase is asynchronous—including the FastAPI routers and SurrealDB queries—pytest needs `pytest-asyncio` to handle event loops and allow `await` inside test functions. Without it, async coroutines would fail to execute during test collection.

### Where are the shared test fixtures defined in open-notebook?

Shared fixtures are defined in [`tests/conftest.py`](https://github.com/lfnovo/open-notebook/blob/main/tests/conftest.py). This file exports reusable assets such as `api_client` and `test_notebook`, providing a clean async environment and automatic teardown after each test run.