Makefile

This guide documents all available Makefile tasks for development, testing, building, and CI operations.

Quick Start

To see all available commands with brief descriptions:

make help

Development Tasks

Starting Development Servers

# Start development instance with backend and dashboard
make start-dev

# Start only frontend development server (requires separate backend)
make start-dev-frontend

These commands install dependencies first if needed and start HARP with reasonable defaults.

To customize services or options:

# Override services to start
make start-dev HARP_SERVICES="server dashboard"

# Add extra options
make start-dev HARP_MORE_OPTIONS="--verbose"

# Customize examples
make start-dev HARP_OPTIONS="--example sqlite --example proxy:httpbin"

Dependency Installation

# Install all dependencies (backend + frontend) without dev tools
make install

# Install all dependencies including dev tools (recommended)
make install-dev

# Install only backend dependencies
make install-backend

# Install only frontend dependencies
make install-frontend

Backend uses uv for Python package management, frontend uses pnpm.

Testing

Running Tests Locally

# Run all tests (backend + frontend)
make test

# Run backend tests only
make test-backend

# Run backend tests and update snapshots
make test-backend-update

# Run frontend tests only (unit + browser + visual)
make test-frontend

# Skip frontend tests
make test TEST_SKIP_FRONT=1

Backend Test Options

The backend test system is highly configurable through environment variables:

# Run specific test targets
make test-backend PYTEST_TARGETS="tests/features/test_http_proxy.py"

# Add pytest options
make test-backend PYTEST_OPTIONS="-v -s -k test_specific_function"

# Control parallel execution
make test-backend PYTEST_CPUS=4  # Use 4 CPUs
make test-backend PYTEST_CPUS=1  # Run serially

# Combine options
make test-backend PYTEST_TARGETS="harp" PYTEST_OPTIONS="-v" PYTEST_CPUS=2

Available environment variables:

  • PYTEST: Path to pytest executable (default: uv run pytest)

  • PYTEST_TARGETS: Test paths to run (default: harp harp_apps tests)

  • PYTEST_CPUS: Number of parallel workers (default: auto)

  • PYTEST_OPTIONS: Additional pytest arguments

Frontend Test Options

# Run unit tests only
cd harp_apps/dashboard/frontend && pnpm test:unit

# Run browser tests
cd harp_apps/dashboard/frontend && pnpm test:browser

# Update unit test snapshots
make test-frontend-update

# Update visual UI snapshots
make test-frontend-ui-update

Coverage Reports

# Generate coverage report for backend
make coverage

This generates an HTML coverage report in docs/_build/html/coverage/.

Code Quality

Formatting

# Format everything (backend + frontend)
make format

# Format backend only (ruff)
make format-backend

# Format frontend only (eslint, prettier)
make format-frontend

Type Checking and QA

# Generate TypeScript types from Python models
make types

# Run pre-QA checks (types, format, reference docs)
make preqa

# Run full QA suite (preqa + tests)
make qa

# Run QA with all database backends (slower)
make qa-full

# Run QA without frontend tests
make qa-nofront TEST_SKIP_FRONT=1

Frontend Linting

# Lint and build frontend (type checking)
make lint-frontend

Frontend Development

Building Frontend Assets

# Build production frontend assets
make build-frontend

This compiles TypeScript and bundles the frontend into harp_apps/dashboard/web/.

Frontend Development Server

Frontend development is typically done with the dev server started by make start-dev-frontend, but you can also use the frontend tools directly:

cd harp_apps/dashboard/frontend

# Start dev server
pnpm dev

# Build for production
pnpm build

# Run Storybook component explorer
pnpm ui:serve

Documentation

# Generate API reference documentation
make reference

# Build HTML documentation
make docs

# Start live-reload documentation server
make docs-dev

The documentation is built with Sphinx and placed in docs/_build/html/.

Benchmarks

# Run benchmarks
make benchmark

# Run and save benchmark results
make benchmark-save

# Customize benchmark runs
make benchmark BENCHMARK_MIN_ROUNDS=500 BENCHMARK_OPTIONS="--verbose"

Benchmarks use pytest-benchmark to measure performance. Results are saved in .benchmarks/ and can be compared across runs. The benchmark-save target runs more iterations for stable results.

Available benchmark variables:

  • BENCHMARK_OPTIONS: Additional benchmark options

  • BENCHMARK_MIN_ROUNDS: Minimum benchmark iterations (default: 100, 500 for save)

Docker Image Tasks

Docker images are built from pre-built Python wheels, ensuring consistency with the release process.

Building Images

HARP provides two Docker build approaches:

  1. buildc - Builds from local wheel (recommended for development and testing)

  2. buildc-pypi - Builds from PyPI package (for validating releases)

# Build from local wheel (builds wheel first, then Docker image)
make buildc

# Build with Python 3.13
make buildc PYTHON_VERSION=3.13

# Build with Python 3.14 (default)
make buildc PYTHON_VERSION=3.14

# Build for specific platform
make buildc DOCKER_PLATFORM=linux/amd64

# Build with custom tags
make buildc DOCKER_TAGS="1.0.0 latest"

# Build from PyPI (requires VERSION)
make buildc-pypi VERSION=0.9.0

# Build from PyPI with Python 3.13
make buildc-pypi VERSION=0.9.0 PYTHON_VERSION=3.13

The buildc target automatically:

  1. Builds a Python wheel (make wheel)

  2. Creates a Docker image installing the wheel using Dockerfile

  3. Tags the image appropriately

The buildc-pypi target:

  1. Requires VERSION parameter specifying which PyPI package version to install

  2. Creates a Docker image installing from PyPI using Dockerfile.pypi

  3. Useful for validating published releases work correctly

Image Management

# Push image to registry
make pushc

Running Containers

# Run container interactively
make runc

# Run with custom command
make runc DOCKER_RUN_COMMAND="server --help"

# Open shell in container
make runc-shell

The --init flag is automatically added for proper signal handling.

Available Docker environment variables:

  • DOCKER_IMAGE: Image name (default: harp-proxy)

  • DOCKER_TAGS: Additional tags to apply

  • DOCKER_TAGS_SUFFIX: Suffix for image tags

  • DOCKER_OPTIONS: Additional Docker options

  • DOCKER_RUN_OPTIONS: Additional run options

  • DOCKER_RUN_COMMAND: Command to run in container

  • DOCKER_PLATFORM: Target platform (default: auto-detected from host architecture)

  • PYTHON_VERSION: Python version for Docker image (default: 3.14)

Cleanup

# Clean everything
make clean

# Clean frontend node_modules only
make clean-frontend-modules

# Clean distribution files
make clean-dist

# Clean documentation builds
make clean-docs

Building Python Wheels

# Build distributable Python wheel
make wheel

This creates a sandboxed environment, builds the frontend, packages everything, and validates the wheel with twine.

Miscellaneous

# Count lines of code
make cloc

# Optimize images in documentation
make optimize-images

Common Workflows

Starting a New Feature

# 1. Install dependencies
make install-dev

# 2. Start development environment
make start-dev

# 3. Run tests as you develop
make test-backend PYTEST_OPTIONS="-v -s"

# 4. Format code before committing
make format

# 5. Run full QA suite
make qa

Debugging CI Failures Locally

CI tests run natively in GitHub Actions runners, so you can reproduce CI issues locally:

# 1. Install dependencies (same as CI)
make install-dev

# 2. Run the same tests as CI
make test-backend

# With specific options
PYTEST_OPTIONS="-v -k test_name" make test-backend

# 3. Run specific test file
uv run pytest tests/specific_test.py -v

# 4. Use testcontainers for database tests (like CI)
TESTCONTAINERS_RYUK_DISABLED=true uv run pytest tests/...

For more details on the CI process and troubleshooting, see ci.

Working with Frontend

# 1. Install frontend dependencies
make install-frontend

# 2. Start frontend dev server (needs backend separately)
make start-dev-frontend

# 3. In another terminal, run frontend tests
cd harp_apps/dashboard/frontend
pnpm test:unit

# 4. Build production assets when ready
make build-frontend

Best Practices

  1. Always use ``make install-dev`` before starting development to ensure all dependencies (including playwright browsers) are installed.

  2. Use Makefile tasks instead of direct commands to ensure consistency with CI and avoid configuration drift.

  3. Run ``make format`` before committing to avoid formatting issues in CI.

  4. Use ``TEST_SKIP_FRONT=1`` when working on backend-only changes to speed up test runs.

  5. Set ``PYTEST_CPUS=1`` when debugging to avoid parallel execution issues.

  6. Build Docker images from wheels using make buildc to ensure the same process as CI/CD and releases.

Environment Variables Reference

Global

  • NAME: Package name (default: harp-proxy)

  • VERSION: Version string from git

  • UV: Path to uv executable

  • PYTEST: Path to pytest executable

  • PNPM: Path to pnpm executable

  • DOCKER: Path to docker executable

Backend Testing

  • PYTEST: Path to pytest executable (default: uv run pytest)

  • PYTEST_TARGETS: Test paths (default: harp harp_apps tests)

  • PYTEST_CPUS: Parallel workers (default: auto)

  • PYTEST_COMMON_OPTIONS: Common pytest options (default: -n $(PYTEST_CPUS))

  • PYTEST_COVERAGE_OPTIONS: Coverage reporting options

  • PYTEST_OPTIONS: Additional pytest arguments

  • TEST_SKIP_FRONT: Skip frontend tests if set

  • TEST_ALL_DATABASES: Test all database backends if set

Docker

  • DOCKER: Path to docker executable

  • DOCKER_INTERACTIVE: Interactive mode flags (default: auto-detected based on TTY)

  • DOCKER_IMAGE: Image name (default: harp-proxy)

  • DOCKER_PLATFORM: Target platform (default: auto-detected from host architecture)

  • DOCKER_TAGS: Additional image tags

  • DOCKER_TAGS_SUFFIX: Suffix for image tags

  • DOCKER_BUILD_OPTIONS: Docker build options

  • DOCKER_OPTIONS: Additional Docker CLI options

  • DOCKER_RUN_OPTIONS: Additional docker run options

  • DOCKER_RUN_COMMAND: Container command

  • DOCKER_NETWORK: Docker network name (default: harp)

  • PYTHON_VERSION: Python version for Docker image builds (default: 3.14)

Frontend

  • PNPM: Path to pnpm executable

  • TEST_SKIP_FRONT: Skip frontend tests if set

Development

  • HARP_OPTIONS: Runtime options for start-dev (default: --example sqlite --example proxy:httpbin)

  • HARP_MORE_OPTIONS: Additional runtime options

  • HARP_SERVICES: Services to start (default: server dashboard)

UV/Build Tools

  • UV: Path to uv executable

  • UVX: Path to uvx executable

  • UV_RUN: UV run command prefix

  • UV_SYNC_OPTIONS: Options for uv sync

  • SED: Path to sed executable (gsed or sed)