Example module — reference implementation for ModuleTester adoption #14

Description

Create a self-contained example module (either as an internal moduletester/example/ package or a separate repository) that demonstrates a complete ModuleTester integration from scratch. This serves as a reference implementation that teams can copy and adapt when adding ModuleTester to their own Python projects.

The example should simulate a realistic use case: a Python package with mixed test types (unit tests, integration tests, manual validation tests) and a fully configured ModuleTester setup including test discovery, configuration, and report generation.

Motivation

• New users currently have no turnkey example to follow.
• Existing real-world integrations are in private/internal projects and cannot be shared.
• A reference implementation reduces onboarding friction and demonstrates best practices.

Expected content

The example module should include:

1. A minimal Python package (example_project/) with:

   • A few simple modules (e.g., a calculator, a data processor)
   • Unit tests using pytest (tests/unit/)
   • Integration/validation tests using # guitest: show markers (tests/validation/)
   • At least one manual test requiring human validation

2. Full ModuleTester configuration:

   • moduletester.ini with all commonly used options
   • Custom test categories (unit, integration, manual)
   • Proper # guitest: annotations demonstrating all directives

3. Documentation:

   • README explaining the structure and how to run
   • Comments in configuration files explaining each option
   • Step-by-step guide: "How to add ModuleTester to your project"

4. Generated outputs (committed as examples):

   • Sample HTML report
   • Sample test plan export

Implementation ideas

Option A — Internal module (moduletester/example/):

• Ships with ModuleTester itself
• Can be used as a template via moduletester init command
• Always in sync with the current version

Option B — Separate repository (e.g., moduletester-example):

• Independent lifecycle, can be updated without releasing ModuleTester
• Easier to fork and adapt
• CI can validate it against the latest ModuleTester release

Acceptance criteria

• Example package with at least 3 modules and 10+ test cases
• Mix of test types: unit (pytest), GUI validation (guitest), manual
• Complete moduletester.ini with comments explaining each option
• README with step-by-step adoption guide
• Sample generated reports (HTML) committed as reference
• All tests pass when run with ModuleTester
• Can be used as a template for new projects