Skip to main content

Gherkin Implementation Plan

1. Vision & Objectives​

To transition WepNG from a "Legacy Monolith" to a "Verified System" by using Gherkin (Reqnroll) to document business requirements as executable tests.

Why Gherkin?​

  1. Documentation as Code: Replaces stale Word docs/Wikis with tests that fail if they are wrong.
  2. Safety Net: "Characterization Tests" lock in current behavior before we refactor for .NET Core/Docker.
  3. Bridge: Allows Business (Product Owners) to read/validate logic without knowing C#.

2. Roadmap Phases​

Phase 1: Documentation & Specification (Current)​

Goal: Use Gherkin to capture business knowledge before writing code.

  • Specs Directory: Create docs/specs to centralize behavior definitions.
  • Workflow:
    1. Feature File: Describe behavior in plain English (Gherkin).
    2. Pseudo-code Mapping: Briefly describe which classes/methods trigger the behavior (e.g., FeeController.Create calls FeeService.Validate).
  • Pilot: Document FeeController validation logic.

Phase 2: Foundation (Future)​

Goal: Establish the testing infrastructure to execute Phase 1 specs.

  • Technical Stack:
    • Framework: Reqnroll.
    • Runner: xUnit.
    • Project: WepNG.Tests.Specs (.NET Framework 4.8).
  • Infrastructure:
    • Add project to Solution.
    • Bind Phase 1 Gherkin steps to C# code.

Phase 3: Expansion (Core Domains)​

Goal: Cover critical hotspots identified in Hotspot Analysis.

  • Priority 1: Orders (Creation logic).
  • Priority 2: WepAccess (Authorization rules).
  • Priority 3: Invoicing (Net Cost calculation).

3. Workflow (Documentation First)​

  1. Analyze: Read legacy code to understand the "Hidden Rules".
  2. Document: Write *.feature in docs/specs/[Context].
  3. Map: Write a companion *.mapping.md with Pseudo-code explaining how to test it (e.g., "Mock IDbContext, call Save(), assert ErrorList").
  4. Review: Validate requirements with Product Owner / Team.

4. Risks & Mitigations​

RiskMitigation
Database StateUse transaction rollback or dedicated cleanup steps.
Legacy CouplingStart with Integration Tests (Phase A) before attempting Unit Tests.
PerformanceTag slow integration tests as @integration to run them separately if needed.
DesyncDocs might drift from code if not executable. Mitigation: Periodic review until Phase 2 is active.
Ambiguity"Magic" steps in Gherkin. Mitigation: Strict mapping.md requirements (Pseudo-code).