DR-003: Use Three-Layer Testing Approach (Rule/Scenario/Unit Test)

Status

[x] Accepted
[ ] Proposed
[ ] Rejected
[ ] Deprecated
[ ] Superseded

Date: 2025-11-03

Context

Testing needs: executable business requirements, collaboration, traceability, compliance, multi-language support.

Problem: How to bridge business requirements and technical implementation?

Decision

Three-layer testing with single specification.feature file:

Layer 1 - Rules: Gherkin Rule blocks (acceptance criteria from Example Mapping Blue Cards) Layer 2 - Scenarios: Gherkin Scenarios under Rules (examples from Green Cards) Layer 3 - Unit Tests: Go unit tests (*_test.go)

Organization:

specs/<module>/<feature>/specification.feature  # Rules + Scenarios
go/eac/specs/impl/<module>/steps.go             # Step definitions
go/eac/<module>/*_test.go                       # Unit tests

Example:

Feature: cli_init-project
  Rule: System initializes project structure
    @success @ac1
    Scenario: Initialize in empty directory
      Given I am in an empty directory
      When I run "r2r init"
      Then the project structure should be created

Mapping: Feature → Feature ID, Rule → Blue Card, Scenario → Green Card, @ac1 → acceptance criterion link

Consequences

Positive: Traceability, stakeholder-readable, single source, compliance support, multi-language

Negative: Learning curve (Gherkin, DDD concepts), workshop overhead, slower execution

Alternatives Considered

Separate Rule/Scenario Files: Rejected - duplication, sync issues
Unit Tests with Separate Docs: Rejected - divergence, no executable requirements
Gherkin Without Rule Blocks: Rejected - no Acceptance Criteria

None

Tutorials | How-to Guides | Explanation | Reference

You are here: Reference — information-oriented technical descriptions of the system.