Skip to content
Skills Library
Programming · Writing

test-case-documentation

/test-case-documentation

Generate comprehensive test case documentation from test code, test framework output, existing test docs, and source code context. Use when documenting test suites, creating test specifications, generating test coverage reports, onboarding developers to testing practices, or preparing QA documentation. Analyzes test functions (pytest, unittest) to extract test names, docstrings, assertions, and organization, then produces structured markdown with both overview-level summaries and detailed test case specifications including purpose, preconditions, steps, expected results, and test data. Trigger

Repository
Skills-4-SE ↗
Licence
Apache-2.0
Last repository change
21.08.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.08.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/extract_tests.py

What it does and when to use it

Generate comprehensive test case documentation from test code, test framework output, existing test docs, and source code context. Use when documenting test suites, creating test specifications, generating test coverage reports, onboarding developers to testing practices, or preparing QA documentation. Analyzes test functions (pytest, unittest) to extract test names, docstrings, assertions, and organization, then produces structured markdown with both overview-level summaries and detailed test case specifications including purpose, preconditions, steps, expected results, and test data. Trigger

Original author description

Generate comprehensive test case documentation from test code, test framework output, existing test docs, and source code context. Use when documenting test suites, creating test specifications, generating test coverage reports, onboarding developers to testing practices, or preparing QA documentation. Analyzes test functions (pytest, unittest) to extract test names, docstrings, assertions, and organization, then produces structured markdown with both overview-level summaries and detailed test case specifications including purpose, preconditions, steps, expected results, and test data. Trigger

How it works

  1. Overview
  2. Workflow
  3. Tips for Effective Test Documentation
  4. Common Documentation Patterns
  5. Automation Opportunities
  6. Reference
Original SKILL.md headings · 557 lines, 1,625 words
SKILL.md preview
---
name: test-case-documentation
description: Generate comprehensive test case documentation from test code, test framework output, existing test docs, and source code context. Use when documenting test suites, creating test specifications, generating test coverage reports, onboarding developers to testing practices, or preparing QA documentation. Analyzes test functions (pytest, unittest) to extract test names, docstrings, assertions, and organization, then produces structured markdown with both overview-level summaries and detailed test case specifications including purpose, preconditions, steps, expected results, and test data. Triggers when users ask to document tests, generate test specifications, create test reports, summarize test coverage, or explain what tests do.
---

# Test Case Documentation

## Overview

Generate comprehensive, structured documentation for test suites by analyzing test code, framework output, and source context to produce both overview summaries and detailed test case specifications.

## Workflow

### 1. Understand Documentation Needs

Determine what documentation is needed:

**Questions to ask:**
- What test suites need documentation?
- Is this for developers, QA, or stakeholders?
- Focus on overview or detailed specifications?
- Include coverage analysis?

**Identify test location:**
```bash
# Find test files
find . -name "test_*.py" -o -name "*_test.py"

# Count test files
find . -name "test_*.py" | wc -l

# Check test framework
grep -r "import pytest\|import unittest" tests/
```

### 2. Extract Test Information

Gather test data from multiple sources.

#### Source 1: Test Code Analysis

Use the bundled script to extract test metadata:

```bash
# Extract tests from directory
python scripts/extract_tests.py /path/to/tests

# Exclude specific directories
python scripts/extract_tests.py /path/to/tests venv,.venv,__pycache__
```

**What it extracts:**
- Test function names
- Test classes and organization
- Docstrings
- Test types (unit, integration, e2e)
- Pytest markers/tags
- File locations and line numbers

**Manual extraction:**

Read test files to understand:

```python
def test_user_registration_with_valid_data():
    """
    Test successful user registration with valid input.

    Given: Valid email, username, and password
    When: User submits registration form
    Then: User account is created and welcome email sent
    """
    # Extract: purpose, preconditions, expected behavior
    user_data = {"email": "test@example.com", ...}  # Extract: test data
    result = service.register(user_data)  # Extract: operation
    assert result.success  # Extract: assertions/expected results
    assert result.user_id > 0
```

**Key information to extract:**
- Test purpose (from name and docstring)
- Test data (sample inputs)
- Operations performed
- Assertions (expected outcomes)
- Setup and teardown (fixtures)

#### Source 2: Test Framework Output

Capture test execution results:

```bash
# Run tests with verbose output
pytest tests/ -v > test_output.txt

# Run with detailed output
pytest tests/ -v --tb=short > test_results.txt

# Generate coverage report
pytest tests/ --cov=src --cov-report=term-missing > coverage.txt
```

**Extract from output:**
- Which tests passed/failed
- Execution time
- Coverage percentages
- Missing coverage areas

#### Source 3: Existing Test Documentation

Check for existing docs:

```bash
# Look for test documentation
find . -name "*test*.md" -o -name "TEST*.md"

# Check for test plans
find . -name "*test*plan*.md"

# Look for docstrings in conftest.py
cat tests/conftest.py
```

#### Source 4: Source Code Context

Understand what's being tested:

```bash
# Find source files related to tests
# test_user_service.py -> user_service.py
ls src/user_service.py

# Read source to understand functionality
cat src/user_service.py
```

### 3. Organize Test Information

Structure tests hierarchically.

See [documentation-templates.md](references/documentation-templates.md) for detailed templates.

**Organization structure:**

```
Test Suite Overview
├── Summary Statistics
├── Test Organization (directory structure)
├── Coverage Summary
└── Test Files
    ├── File 1: test_user_service.py
    │   ├── TestUserRegistration (class)
    │   │   ├── test_valid_registration (unit)
    │   │   ├── test_duplicate_email (unit)
    │   │   └── test_weak_password (unit)
    │   └── TestUserAuthentication (class)
    │       ├── test_login_success (unit)
    │       └── test_login_failure (unit)
    └── File 2: test_api.py
        └── test_full_workflow (integration)
```

**Categorize by:**
- Test type (unit, integration, e2e)
- Module/feature tested
- Priority/criticality
- Test status (passing, failing, skipped)

### 4. Generate Documentation

Create structured markdown documentation.

#### Level 1: Overview Documentation

High-level summary for project understanding:

```markdown
# Test Suite: User Management

**Last Updated:** 2026-02-15
**Total Tests:** 42
**Coverage:** 87%
**Status:** ✅ 40 passing, ❌ 2 failing

## Summary

Comprehensive test suite for user management functionality including registration,
authentication, profile management, and user data export.

## Test Statistics

- **Unit Tests:** 28 (67%)
- **Integration Tests:** 12 (28%)
- **End-to-End Tests:** 2 (5%)

## Test Organization

```
tests/
├── unit/
│   ├── test_user_service.py (15 tests)
│   ├── test_auth_service.py (8 tests)
│   └── test_validators.py (5 tests)
├── integration/
│   ├── test_api.py (10 tests)
│   └── test_workflows.py (2 tests)
└── e2e/
    └── test_complete_flows.py (2 tests)
```

## Coverage by Module

| Module | Coverage | Tests | Priority |
|--------|----------|-------|----------|
| user_service.py | 95% | 15 | High |
| auth_service.py | 88% | 8 | High |
| validators.py | 94% | 5 | Medium |

## Quick Start

```bash
# Run all tests
pytest tests/

# Run unit tests only
pytest tests/unit/

# Run with coverage
pytest --cov=src tests/
```
```

#### Level 2: Detailed Test Documentation

Detailed specifications for each test:

```markdown
## Test File: test_user_service.py

**Path:** `tests/unit/test_user_service.py`
**Tests:** 15
**Coverage:** 95%

---

### Class: TestUserRegistration

Tests for user registration functionality.

---

#### Test: test_user_registration_with_valid_data

**Type:** Unit Test
**Line:** 45
**Status:** ✅ Passing
**Tags:** user, authentication

**Purpose:**
Verify that a new user can successfully register with valid email, username, and password.

**Preconditions:**
- Database is empty (no existing users)
- Email validation service is mocked

**Test Data:**
```python
user_data = {
    "email": "test@example.com",
    "username": "testuser",
    "password": "SecurePass123!"
}
```

**Test Steps:**
1. Create user data dictionary with valid fields
2. Call `UserService.register(user_data)`
3. Verify user record is created in database
4. Verify user ID is returned
5. Verify password is hashed (not plain text)

**Assertions:**
- `assert result.success == True`
- `assert result.user_id > 0`
- `assert User.query.count() == 1`
- `assert created_user.password != "SecurePass123!"`

**Expected Result:**
- User created with status "active"
- User ID returned (positive integer)
- Password stored as hash
- No errors raised

**Actual Result:** ✅ Pass (0.12s)

**Related Tests:**
- `test_user_registration_with_duplicate_email` - Tests duplicate handling
- `test_user_registration_with_weak_password` - Tests password validation

**Source Code Tested:**
`src/user_service.py:67-89` - `UserService.register()`

---

#### Test: test_user_registration_with_duplicate_email

**Type:** Unit Test
**Line:** 78
**Status:** ✅ Passing

**Purpose:**
Verify that registration fails when email already exists.

**Preconditions:**
- User with email "test@example.com" already exists in database

**Test Data:**
```python
existing_user = User(email="test@example.com", username="existing")
duplicate_data = {
    "email": "test@example.com",  # Duplicate
    "username": "newuser",
    "password": "ValidPass123"
}
```

**Expected Result:**
- `DuplicateEmailError` exception raised
- Error message: "Email already registered"
- No new user record created

**Actual Result:** ✅ Pass (0.08s)

---

### Class: TestUserAuthentication

Tests for user login and authentication.

[Continue with more tests...]
```

### 5. Include Coverage Analysis

Identify tested and untested areas.

```markdown
## Test Coverage Analysis

**Overall Coverage:** 87%

### High Coverage Areas

**user_service.py** - 95% coverage
- ✅ User registration (all paths tested)
- ✅ User update (all paths tested)
- ✅ User deletion (all paths tested)
- ⚠️ Uncovered: External API error handling (lines 145-150)

**Recommendation:** Add test case `test_user_registration_with_api_failure`

### Medium Coverage Areas

**payment_service.py** - 85% coverage
- ✅ Payment processing (happy path tested)
- ✅ Payment validation (tested)
- ⚠️ Uncovered: Timeout handling (lines 67-72)
- ⚠️ Uncovered: Retry logic (lines 89-95)

**Recommendations:**
- Add `test_payment_processing_timeout`
- Add `test_payment_retry_on_failure`

### Low Coverage Areas

**export_service.py** - 78% coverage
- ✅ Basic export (tested)
- ❌ Large dataset handling (not tested)
- ❌ Memory overflow scenarios (not tested)

**Recommendations:**
- Add `test_export_large_dataset`
- Add `test_export_memory_limit`
```

### 6. Document Test Execution

Include how to run tests:

```markdown
## Test Execution Guide

### Running All Tests

```bash
# Run entire test suite
pytest tests/

# Run with coverage report
pytest --cov=src --cov-report=html tests/

# Run with detailed output
pytest tests/ -v
```

### Running Specific Tests

```bash
# Run tests in specific file
pytest tests/unit/test_user_service.py

# Run specific test class
pytest tests/unit/test_user_service.py::TestUserRegistration

# Run specific test
pytest tests/unit/test_user_service.py::TestUserRegistration::test_valid_registration

# Run tests with specific marker
pytest -m "unit" tests/
pytest -m "integration" tests/
```

### Test Configuration

**pytest.ini:**
```ini
[pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
markers =
    unit: Unit tests
    integration: Integration tests
    slow: Slow running tests
```

### Continuous Integration

Tests run automatically on:
- Pull requests to main branch
- Daily at 2am UTC
- Before deployment

**CI Command:**
```bash
pytest tests/ --cov=src --cov-report=xml --junitxml=test-results.xml
```
```

### 7. Present Documentation

Finalize and share the documentation.

**Documentation structure:**

```
docs/testing/
├── README.md (overview + quick start)
├── test-suite-overview.md (high-level summary)
├── test-specifications/
│   ├── user-management-tests.md
│   ├── payment-tests.md
│   └── api-tests.md
├── test-coverage-report.md
└── test-execution-guide.md
```

**Present to stakeholders:**
- Developers: Detailed specs + coverage
- QA: Test execution + expected results
- Management: Overview + statistics
- New team members: Overview + execution guide

## Tips for Effective Test Documentation

**Focus on clarity:**
- Use clear, descriptive test names
- Document the "why" not just the "what"
- Include expected vs actual behavior
- Show test data examples

**Keep it current:**
- Update docs when tests change
- Include last updated date
- Link to source code line numbers
- Note test status (passing/failing)

**Make it actionable:**
- Include reproduction steps
- Provide test execution commands
- Show configuration requirements
- Link related tests

**Organize logically:**
- Group by feature/module
- Order by priority or type
- Use consistent formatting
- Include table of contents for long docs

**Include context:**
- Explain preconditions
- Document test data
- Note dependencies
- Link to requirements or tickets

## Common Documentation Patterns

**Given-When-Then format:**
```python
def test_user_registration():
    """
    Given: A new user with valid email and password
    When: They submit the registration form
    Then: Their account is created and activated
    """
```

**Arrange-Act-Assert pattern:**
```python
def test_calculate_total():
    """Test order total calculation with tax."""
    # Arrange
    order = Order(items=[Item(price=100)])

    # Act
    total = order.calculate_total(tax_rate=0.1)

    # Assert
    assert total == 110
```

**Test matrices for combinatorial tests:**

| Input A | Input B | Expected |
|---------|---------|----------|
| Valid   | Valid   | Success  |
| Valid   | Invalid | Error A  |
| Invalid | Valid   | Error B  |
| Invalid | Invalid | Error C  |

## Automation Opportunities

**Auto-generate from CI:**
```bash
# Run tests and generate documentation
pytest tests/ --json-report --json-report-file=test-report.json

# Parse JSON and generate markdown
python generate_test_docs.py test-report.json > docs/test-report.md
```

**Keep docs in sync:**
- Git hooks to update docs when tests change
- CI checks for undocumented tests
- Automated coverage reports
- Test status badges in README

## Reference

For documentation templates and examples, see [documentation-templates.md](references/documentation-templates.md).
Files in this package (3)
  • SKILL.md 13 KB
  • references/documentation-templates.md 10 KB
  • scripts/extract_tests.py 8 KB

Versions

The database has no other skills named test-case-documentation.

Database snapshot: 13.11.2026 · package version e8a1977b05be (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100unittest-test-creator
    Create unittest test creator operations. Auto-activating skill for Test Automation. Triggers on: unittest test creator, unittest test creator Part of the Test Automation skill category. Use when writing or running tests. Trigger with phrases like "unittest test creator",…
  • 100unit-test-generator
    Automatically generates comprehensive unit tests for functions, classes, and modules. Use when you need to create tests for Python (pytest, unittest) or Java (JUnit, TestNG) code. Generates tests with comprehensive coverage including happy paths, edge cases, and error…
  • 100generating-test-reports
    Generate comprehensive test reports with metrics, coverage, and visualizations. Use when performing specialized testing. Trigger with phrases like "generate test report", "create test documentation", or "show test metrics".
  • 100generating-test-reports
    Generate comprehensive test reports with metrics, coverage, and visualizations. Use when performing specialized testing. Trigger with phrases like "generate test report", "create test documentation", or "show test metrics".
  • 100assertion-synthesizer
    Generate test assertions from existing code implementation. Use when the user has implementation code without tests or incomplete test coverage, and needs assertions synthesized by analyzing the code's behavior, inputs, outputs, and state changes. Supports Python…
  • 95unittest-skill
    Generates Python unittest tests. Built-in testing framework with TestCase, setUp/tearDown, and assertion methods. Use when user mentions "unittest", "TestCase", "self.assertEqual", "Python unittest". Triggers on: "unittest", "TestCase", "self.assertEqual", "Python unittest" (not pytest).

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.