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

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

# 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, 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 (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, 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 supports flexible testing workflows with coverage and parallelization
• Documentation in 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, 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 (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.

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