Scope

Audit the test suite (tests/) and acceptance tests (features/) for coverage gaps, outdated patterns, and reliability issues.

What to Review

Coverage Gaps

• Run coverage analysis (uv run pytest --cov=docx --cov-report=html) and identify modules/functions with low coverage
• Focus on:
  • docx/oxml/ — are all element classes tested?
  • docx/ model classes — are all public methods tested?
  • Error paths — are exceptions and validation errors tested?
  • Edge cases — empty inputs, missing optional elements, boundary values

Test Quality

• Are tests testing behaviour or implementation details?
• Are there tests that would pass even if the code was broken (tautological tests)?
• Are mocks overused where real objects would be better?
• Are there tests that depend on execution order?

Outdated Patterns

• Replace unittest.TestCase with plain pytest functions where appropriate
• Replace setUp/tearDown with pytest fixtures
• Use pytest.raises instead of try/except in tests
• Use pytest.mark.parametrize for data-driven tests
• Replace manual assertions with more specific pytest assertions

Acceptance Tests (behave)

• Are the .feature files up to date with current functionality?
• Are there missing acceptance test scenarios?
• Do step definitions have proper error messages?

Flaky Tests

• Are there tests that depend on filesystem state, timing, or external resources?
• Are temp files cleaned up properly?

Missing Test Infrastructure

• Is there a conftest.py with shared fixtures?
• Are test fixtures (sample .docx files) well-organised and documented?

Output

• Coverage report with specific gaps identified
• List of tests to modernise (unittest → pytest)
• List of missing test scenarios
• Suggested conftest.py fixtures for common patterns