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

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

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.

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:

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:

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:

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:

# 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 – Validates message routing, FIFO semantics, and error handling in the IM channel system.
• test_uploads_router.py – Tests secure file upload endpoints, sandbox synchronization, and file-type validation.
• 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 – Checks background executor pools, timeout handling, and retry logic for sub-agent orchestration.
• test_memory_upload_filtering.py – Ensures debounced fact extraction and correct storage formatting for memory systems.
• 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 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:

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

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