plaintest 0.1.0

A pytest plugin and CLI tool for managing plain-text test cases with markdown documentation

plaintest

A pytest plugin and CLI tool for managing plain-text test cases with markdown documentation.

Overview

plaintest helps you bridge the gap between human-readable test case documentation and automated tests. Write your test cases in simple markdown files, link them to pytest tests using decorators, and generate beautiful HTML reports showing test coverage and results.

Rationale

Many teams struggle with test documentation scattered across multiple systems: requirements in Jira, test cases in TestRail, implementation details in code comments. This fragmentation makes it hard to understand what's being tested and why. By keeping test cases as markdown files in your repository alongside your code, you maintain a single source of truth that's version-controlled, code-review friendly, and easily accessible to both humans and LLMs.

Changes to test specifications go through the same PR process as code changes, ensuring consistency and traceability.

Installation

pip install plaintest

Or with uv:

uv add plaintest

Quick Start

1. Initialize your test cases directory:

plaintest init

2. Create a test case:

plaintest add "User login functionality"

This creates a markdown file like test-cases/001/case.md:

---
title: User login functionality
tags: []
---

## Steps


## Expected

3. Link a pytest test to the test case:

import pytest

@pytest.mark.tc("001")
def test_user_login():
    # Your test implementation
    assert True

4. Generate a coverage report:

plaintest report

Configuration

Add configuration to your pyproject.toml:

[tool.plaintest]
test_cases_dir = "test-cases"

Commands

• plaintest init - Initialize test cases directory
• plaintest add [TITLE] - Interactively add new test case(s)
• plaintest report - Generate terminal-based coverage report
• plaintest html-report - Generate side-by-side HTML report

License

MIT