# Understanding the Tests Directory in makeplane/plane: Purpose and Structure

> Explore the tests directory in makeplane/plane. Learn how its automated test suite ensures backend API correctness, stability, and security via unit, contract, and smoke tests.

- Repository: [Plane/plane](https://github.com/makeplane/plane)
- Tags: internals
- Published: 2026-06-25

---

**The `tests` directory in makeplane/plane houses the automated test suite that validates the correctness, stability, and security of Plane’s backend API through unit, contract, and smoke test layers.**

The quality assurance strategy for Plane, an open-source project management platform, centers on a comprehensive test suite located in `apps/api/plane/tests/`. This **tests directory** organizes validation into three distinct categories that enable rapid feedback during development while ensuring API contracts remain stable. Each category serves a specific purpose in the software lifecycle, from isolated logic verification to end-to-end system health checks.

## Three-Tier Test Organization

The `tests` directory implements a hierarchical testing strategy that separates concerns by scope and execution speed.

### Unit Tests: Isolated Component Logic

Unit tests reside in `apps/api/plane/tests/unit/` and focus on verifying individual components in isolation. These tests validate **models**, **serializers**, **middleware**, **utilities**, **background tasks**, and **settings** without external dependencies. Because they avoid database or network calls, unit tests execute quickly and provide immediate feedback during the development cycle. The directory includes specialized security tests, such as SSRF protection validation in [`apps/api/plane/tests/unit/bg_tasks/test_url_security.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/tests/unit/bg_tasks/test_url_security.py) (lines 6-9), which guards against server-side request forgery vulnerabilities.

### Contract Tests: API Contract Validation

Contract tests in `apps/api/plane/tests/contract/` serve as integration tests that verify the public REST API behaves according to its documented specification. These tests validate endpoints for **projects**, **labels**, **authentication**, and **workspaces**, ensuring that external consumers can rely on consistent response formats and status codes. Unlike unit tests, contract tests exercise the full request-response cycle, confirming that serializers, views, and authentication layers interact correctly.

### Smoke Tests: Critical System Health

Smoke tests located in `apps/api/plane/tests/smoke/` perform minimal end-to-end verification of essential application flows. These tests confirm that the service starts correctly and responds to basic requests, particularly focusing on **authentication flows** and core connectivity. Smoke tests run quickly to verify deployment health without the overhead of the full integration suite.

## Test Execution Orchestration

The [`apps/api/run_tests.py`](https://github.com/makeplane/plane/blob/main/apps/api/run_tests.py) script serves as the primary interface for test execution, translating command-line flags into `pytest` commands with appropriate markers. As implemented in lines 11-18 and 24-36 of [`run_tests.py`](https://github.com/makeplane/plane/blob/main/run_tests.py), the script supports:

- `--unit`: Runs tests marked with `@pytest.mark.unit`
- `--contract`: Executes contract tests with the `contract` marker
- `--smoke`: Validates critical paths using the `smoke` marker
- `--coverage`: Generates coverage reports alongside test results
- `--parallel`: Enables parallel execution for faster feedback
- `--verbose`: Provides detailed output for debugging failures

You can execute specific test categories using the following commands:

```bash

# Run only unit tests for fast logic validation

python apps/api/run_tests.py --unit

# Execute contract tests with coverage reporting

python apps/api/run_tests.py --contract --coverage

# Run smoke tests in parallel with detailed output

python apps/api/run_tests.py --smoke --parallel --verbose

```

## Configuration and Documentation

Shared test fixtures and configuration reside in [`apps/api/plane/tests/conftest.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/tests/conftest.py), providing consistent setup for database states, test users, and mock objects across all test categories. For environment setup and Docker-based execution, the repository includes [`apps/api/plane/tests/RUNNING_TESTS.md`](https://github.com/makeplane/plane/blob/main/apps/api/plane/tests/RUNNING_TESTS.md) (lines 1-4), which documents the required environment variables and container orchestration steps necessary to execute the suite locally.

## Security and Regression Prevention

The test suite guards against regressions through automated validation of every pull request. Security-specific tests, such as those validating URL sanitization in background tasks, detect vulnerabilities early in the development cycle. By isolating security logic in [`unit/bg_tasks/test_url_security.py`](https://github.com/makeplane/plane/blob/main/unit/bg_tasks/test_url_security.py), the suite ensures that protections against SSRF and other injection attacks remain effective as the codebase evolves.

## Summary

The **tests directory in makeplane/plane** provides a robust framework for maintaining code quality:

- **Unit tests** in `apps/api/plane/tests/unit/` validate isolated logic and security controls
- **Contract tests** in `apps/api/plane/tests/contract/` verify API behavior matches public specifications
- **Smoke tests** in `apps/api/plane/tests/smoke/` confirm critical system health
- **Execution orchestration** through [`apps/api/run_tests.py`](https://github.com/makeplane/plane/blob/main/apps/api/run_tests.py) supports flexible testing workflows with coverage and parallelization
- **Documentation** in [`RUNNING_TESTS.md`](https://github.com/makeplane/plane/blob/main/RUNNING_TESTS.md) enables consistent local execution

## Frequently Asked Questions

### How do I run only the unit tests in makeplane/plane?

Execute `python apps/api/run_tests.py --unit` from the repository root. This command invokes `pytest` with the `unit` marker, running only the isolated component tests in `apps/api/plane/tests/unit/` for rapid feedback.

### What is the difference between contract tests and smoke tests?

**Contract tests** validate the complete REST API contract, ensuring that endpoints return correct status codes and data structures for external consumers. **Smoke tests** perform minimal health checks to verify the application starts and critical paths like authentication respond, without exhaustive data validation.

### Where are the test fixtures configured in makeplane/plane?

Shared fixtures are defined in [`apps/api/plane/tests/conftest.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/tests/conftest.py), which provides reusable setup for database connections, test users, and mock objects used across unit, contract, and smoke test categories.

### How does the test suite prevent security regressions?

The suite includes dedicated security tests, such as SSRF protection validation in [`apps/api/plane/tests/unit/bg_tasks/test_url_security.py`](https://github.com/makeplane/plane/blob/main/apps/api/plane/tests/unit/bg_tasks/test_url_security.py) (lines 6-9), which verify that background tasks properly sanitize URLs. These automated checks run alongside functional tests to catch vulnerabilities before they reach production.