# How to Run Tests for DeerFlow: Complete Guide to the Backend Test Suite

> Learn how to run tests for DeerFlow. This guide covers backend test suite execution using make test or pytest for local validation. Run DeerFlow backend tests easily.

- Repository: [Bytedance Inc./deer-flow](https://github.com/bytedance/deer-flow)
- Tags: how-to-guide
- Published: 2026-03-08

---

**Run `make test` from the `backend/` directory after installing dependencies with `make install`, or execute `PYTHONPATH=. uv run pytest backend/tests/ -v` directly to validate the DeerFlow backend locally.**

The DeerFlow repository provides a comprehensive **pytest**-based test suite located in the `backend` package. Whether you are contributing new features to the agent harness or verifying local changes, running tests for DeerFlow ensures that core systems—including message routing, file uploads, and sub-agent orchestration—function correctly in isolation and integration scenarios.

## Prerequisites for Running DeerFlow Tests

Before executing the test suite, ensure your environment meets the repository's toolchain requirements.

- **Python 3.12+** – The [`backend/pyproject.toml`](https://github.com/bytedance/deer-flow/blob/main/backend/pyproject.toml) pins Python to version 3.12 or higher.
- **uv** – The project uses the Astral `uv` package manager for dependency synchronization and test execution. Install it via `curl -LsSf https://astral.sh/uv/install.sh | sh`.
- **Repository structure** – You must run commands from the repository root or the `backend/` directory with `PYTHONPATH` set to resolve imports like `src.channels`.

## Installing Test Dependencies

DeerFlow manages backend dependencies through a Makefile that wraps `uv` commands. To install all development and test dependencies:

```bash
cd backend
make install

```

The `install` target defined in `backend/Makefile` executes `uv sync`, which installs the full dependency group including pytest and coverage tools. This mirrors the environment used in the CI pipeline defined in [`.github/workflows/backend-unit-tests.yml`](https://github.com/bytedance/deer-flow/blob/main/.github/workflows/backend-unit-tests.yml).

## Running the DeerFlow Test Suite

The test suite covers six major backend components. You can execute tests at different granularity levels depending on your debugging needs.

### Run the Full Suite

To execute all backend tests with verbose output:

```bash
make test

```

This command runs `PYTHONPATH=. uv run pytest tests/ -v`, exactly as configured in the CI workflow. It validates the message bus, upload routers, title generation middleware, sub-agent executors, memory extraction, and model factory integrations.

### Run a Single Test Module

Target specific functionality by running individual test files:

```bash
uv run pytest backend/tests/test_channels.py -v
uv run pytest backend/tests/test_uploads_router.py -v
uv run pytest backend/tests/test_subagent_executor.py -v

```

### Run a Specific Test Function

For granular debugging, invoke a single test method using the `::` selector:

```bash
uv run pytest backend/tests/test_channels.py::TestMessageBus::test_publish_and_get_inbound -vv

```

### Advanced pytest Options

Add standard pytest flags for debugging and coverage analysis:

```bash

# Stop after first failure with full traceback

uv run pytest backend/tests/ -x --tb=long

# Run with coverage reporting for the src package

PYTHONPATH=. uv run pytest backend/tests/ --cov=src --cov-report=term-missing

```

## Understanding the Test Architecture

The backend tests in `backend/tests/` verify critical runtime behavior across distinct subsystems:

- **[`test_channels.py`](https://github.com/bytedance/deer-flow/blob/main/test_channels.py)** – Validates message routing, FIFO semantics, and error handling in the IM channel system.
- **[`test_uploads_router.py`](https://github.com/bytedance/deer-flow/blob/main/test_uploads_router.py)** – Tests secure file upload endpoints, sandbox synchronization, and file-type validation.
- **[`test_title_middleware_core_logic.py`](https://github.com/bytedance/deer-flow/blob/main/test_title_middleware_core_logic.py)** – Verifies automatic title generation after the first exchange, including quoting logic and model failure fallbacks.
- **[`test_subagent_executor.py`](https://github.com/bytedance/deer-flow/blob/main/test_subagent_executor.py)** – Checks background executor pools, timeout handling, and retry logic for sub-agent orchestration.
- **[`test_memory_upload_filtering.py`](https://github.com/bytedance/deer-flow/blob/main/test_memory_upload_filtering.py)** – Ensures debounced fact extraction and correct storage formatting for memory systems.
- **[`test_model_factory.py`](https://github.com/bytedance/deer-flow/blob/main/test_model_factory.py)** – Validates end-to-end API conformity and MCP server configuration integration.

Each test module assumes `PYTHONPATH` includes the repository root so that `import src.channels` resolves correctly.

## CI Integration and Automation

The repository's continuous integration uses the same commands you run locally. The workflow file [`.github/workflows/backend-unit-tests.yml`](https://github.com/bytedance/deer-flow/blob/main/.github/workflows/backend-unit-tests.yml) executes `make test` on every pull request, ensuring that changes to `src/` pass the full pytest suite before merging. You can replicate the CI environment locally using Docker:

```bash
docker run --rm -v $(pwd):/app -w /app python:3.12-slim \
    bash -c "pip install uv && cd backend && make install && make test"

```

## Summary

- **Install dependencies** with `make install` inside the `backend/` directory.
- **Run the full suite** using `make test` or `PYTHONPATH=. uv run pytest backend/tests/ -v`.
- **Target specific tests** by module path or function name for faster iteration.
- **Meet requirements** by using Python 3.12+ and the `uv` package manager.
- **Reference CI** configuration in [`.github/workflows/backend-unit-tests.yml`](https://github.com/bytedance/deer-flow/blob/main/.github/workflows/backend-unit-tests.yml) for automation patterns.

## Frequently Asked Questions

### What Python version is required to run DeerFlow tests?

DeerFlow requires **Python 3.12 or higher**, as specified in the backend's [`pyproject.toml`](https://github.com/bytedance/deer-flow/blob/main/pyproject.toml). The CI workflow explicitly sets up Python 3.12 to ensure compatibility with the test suite's dependencies and syntax features.

### Can I run DeerFlow tests without using Make?

Yes. While `make test` provides a convenient wrapper, you can execute the underlying command directly: `PYTHONPATH=. uv run pytest backend/tests/ -v`. Ensure you run this from the repository root so that imports resolve correctly.

### How do I test a specific component like channels or uploads?

Run the relevant test module directly with pytest. For example, `uv run pytest backend/tests/test_channels.py -v` runs only the message bus tests, while `uv run pytest backend/tests/test_uploads_router.py -v` validates upload handling in isolation.

### What test runner does DeerFlow use?

DeerFlow uses **pytest** as its test runner, orchestrated through the `uv` package manager. The configuration supports standard pytest flags for verbosity, coverage (`--cov`), and selective test execution via `-k` expressions or node IDs.