<!-- textlint-disable ja-technical-writing/no-exclamation-question-mark -->

BDD Coder Test Implementation Template

Reference this template when implementing tests for bdd-coder tasks.

Basic Template

# BDD Implementation Task

## Task Summary

[Brief description of feature/functionality to implement]

## Requirements

- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

## Implementation Rules

### Append-First Principle

- **First assertion**: Create NEW test case (new describe block)
- **Second and subsequent assertions**: MUST append to existing test
- **Forbidden**: Creating new test block for same Given/When context
- **Reason**: Preserve Given/When semantic context
- **How**: Use `it.each([...])` or add expects to same it block
- **Exception**: Create new test ONLY if Given/When differs, intent changes, or naming becomes unnatural
- **All phases**: This rule applies during implementation AND refactoring

### Assertion Granularity

- One assertion per test case (separate it blocks OR it.each rows)
- Group related assertions (same Given/When) via it.each parameterization
- Each failure must point to one assertion clearly

### RED-GREEN-REFACTOR Cycle

1. **RED**: Write failing test (test code only, NO implementation)
2. **GREEN**: Write minimal implementation to pass test
3. **REFACTOR**: Improve test and code while keeping tests GREEN

## Coverage Categories

Identify assertions across these categories:

- **Normal**: Happy path with valid inputs
- **Invalid**: Type mismatches, null/undefined, wrong formats, out-of-range values
- **Edge cases**: Boundary values, empty collections, special characters

Example breakdown for function `getRawOSPlatform(runtime)`:

- Normal: Windows, macOS, Linux runtime values
- Invalid: number, null, undefined, wrong string values
- Edge: empty string, whitespace, mixed-case strings

## Test Structure Example (TypeScript/Vitest)

```typescript
describe('Given: runtime parameter provided', () => {
  describe('When: checking normal values', () => {
    describe('Then: Task T01-02 - Detect platform from runtime', () => {
      // Append-first pattern: it.each for grouped assertions
      it.each<[string, PlatformType]>([
        ['windows', 'windows'], // Normal case 1
        ['macos', 'darwin'], // Normal case 2
        ['linux', 'linux'], // Normal case 3
      ])('Should: return %s for %s runtime', (input, expected) => {
        const result = getRawOSPlatform(input as AGRuntimeType);
        expect(result).toBe(expected);
      });
    });
  });

  describe('When: checking invalid values', () => {
    describe('Then: Task T01-02 - Detect platform from runtime', () => {
      // Separate Then block for different When context
      it.each<[unknown]>([
        [null], // Invalid case 1
        [undefined], // Invalid case 2
        [123], // Invalid case 3
        ['invalid'], // Invalid case 4
      ])('Should: return undefined for invalid input %s', (input) => {
        const result = getRawOSPlatform(input as unknown as AGRuntimeType);
        expect(result).toBeUndefined();
      });
    });
  });
});
```

Implementation Checklist

Before Starting:

• Read bdd-coder.md "Append-first principle" section
• Understand Given/When/Then context matching
• Review existing test patterns in project

During Implementation:

• First assertion → Create new test block
• Check Given/When: Same as existing? → Append
• Check Given/When: Different? → Create new Then block
• Verify test name reflects behavior clearly
• Run tests after each assertion (RED → GREEN → REFACTOR)

After All Assertions:

• Review test code: Use it.each effectively
• Review implementation code: Minimal and clean
• All tests PASS

Phase 5: Refactoring Guidance

Splitting Tests:

• Split it.each into separate it() blocks if it improves failure clarity
• Keep splits WITHIN same Then block (same Given/When context)
• Example: it.each([case1, case2, case3]) → three it() under same describe

Technical Debt:

• Fragmented Given/When blocks are acceptable during implementation
• Normalize structure during refactoring phases

Reference

For complete workflow details, see:

<!-- textlint-disable -->

• Main agent doc: .claude/agents/bdd-coder.md
• Core principle: "Append-first principle" in Core Principles section
• Workflo*: "Phase 3: RED-GREEN-REFACTOR Loop" section