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

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. The project specifies Python 3.11 or newer and uses uv as its preferred package manager.

Install the development dependencies from the repository root:

uv sync --dev

This command reads 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:

uv run pytest

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

uv run pytest tests/test_models_api.py

Run a single test function by its fully qualified name:

uv run pytest tests/test_models_api.py::test_create_notebook

Run only the unit tests:

uv run pytest tests/unit/

Generate a coverage report for the open_notebook package:

uv run pytest --cov=open_notebook

Enable verbose output or show printed statements:

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 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. 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 (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.

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:

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

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

Using a Reusable Notebook Fixture

The tests/conftest.py file defines an async test_notebook fixture that creates a temporary notebook and removes it after the test:

# 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 — Declares pytest, pytest-asyncio, and other dev dependencies. It also pins the minimum Python version.
• 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 — Houses shared fixtures for async setup and teardown across the suite.
• 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 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.

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. 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. This file exports reusable assets such as api_client and test_notebook, providing a clean async environment and automatic teardown after each test run.

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