docs(05-01): complete TesterDriver interface + mock drivers plan
- TesterDriver, StreamingTesterDriver interfaces defined - 4 mock drivers: MockUSBDriver, MockDPDriver, MockHDMIDriver, MockFNB58Driver - KnownDevices extended with 4 RoleCableTester placeholder entries - All tests pass, race detector clean
This commit is contained in:
parent
11aea60aee
commit
db287c238f
1 changed files with 126 additions and 0 deletions
126
.planning/phases/05-cable-test-integration/05-01-SUMMARY.md
Normal file
126
.planning/phases/05-cable-test-integration/05-01-SUMMARY.md
Normal file
|
|
@ -0,0 +1,126 @@
|
||||||
|
---
|
||||||
|
phase: 05-cable-test-integration
|
||||||
|
plan: "01"
|
||||||
|
subsystem: testing
|
||||||
|
tags: [go, tester, mock, usb, cable-testing, interface, streaming, channels]
|
||||||
|
|
||||||
|
# Dependency graph
|
||||||
|
requires:
|
||||||
|
- phase: 04-usb-manager-label-printing
|
||||||
|
provides: DeviceRole, DeviceSpec, KnownDevices map in internal/usb/device.go
|
||||||
|
provides:
|
||||||
|
- TesterDriver interface (Connect/Read/Disconnect)
|
||||||
|
- StreamingTesterDriver interface (embeds TesterDriver + Stream())
|
||||||
|
- TestResult struct with all cable measurement fields
|
||||||
|
- LiveReading struct for streaming power/protocol data
|
||||||
|
- MockUSBDriver, MockDPDriver, MockHDMIDriver (deterministic discrete mocks)
|
||||||
|
- MockFNB58Driver (streaming mock with context-based cancellation)
|
||||||
|
- KnownDevices extended with 4 RoleCableTester placeholder entries
|
||||||
|
affects: [05-02-backend-endpoints, 05-03-cable-test-ui, 06-real-driver-impl]
|
||||||
|
|
||||||
|
# Tech tracking
|
||||||
|
tech-stack:
|
||||||
|
added: []
|
||||||
|
patterns:
|
||||||
|
- "TDD red-green for Go interface + mock drivers"
|
||||||
|
- "context.WithCancel for goroutine lifetime in streaming drivers"
|
||||||
|
- "Buffered channel (size 8) with pre-closed channel idiom for Stream() before Connect()"
|
||||||
|
- "Idempotent Disconnect() via bool guard"
|
||||||
|
- "Compile-time interface assertions: var _ Interface = (*Impl)(nil)"
|
||||||
|
|
||||||
|
key-files:
|
||||||
|
created:
|
||||||
|
- internal/tester/driver.go
|
||||||
|
- internal/tester/mock_drivers.go
|
||||||
|
- internal/tester/driver_test.go
|
||||||
|
modified:
|
||||||
|
- internal/usb/device.go
|
||||||
|
|
||||||
|
key-decisions:
|
||||||
|
- "MockFNB58Driver.Stream() before Connect() returns pre-closed channel (not nil) — avoids nil-channel deadlock risk in callers"
|
||||||
|
- "FNB58 goroutine uses context.WithCancel stored on struct so Disconnect() cancels early — satisfies T-05-02 DoS mitigation"
|
||||||
|
- "Placeholder VID:PIDs use dead0:000N pattern — easy to grep, clearly fake, TODO comment dated 2026-04-13"
|
||||||
|
- "StreamingTesterDriver embeds TesterDriver — real FNB58 driver must satisfy both Read() and Stream()"
|
||||||
|
|
||||||
|
patterns-established:
|
||||||
|
- "Streaming driver pattern: Connect() launches goroutine, stores cancelFunc, Disconnect() cancels it"
|
||||||
|
- "Mock driver struct has single bool connected field — minimal state for test clarity"
|
||||||
|
- "Pre-closed channel idiom: ch := make(chan T); close(ch); return ch — for not-ready Stream()"
|
||||||
|
|
||||||
|
requirements-completed: [CBL-01, CBL-02, CBL-03, CBL-04, CBL-07]
|
||||||
|
|
||||||
|
# Metrics
|
||||||
|
duration: 12min
|
||||||
|
completed: 2026-04-10
|
||||||
|
---
|
||||||
|
|
||||||
|
# Phase 05 Plan 01: TesterDriver Interface + 4 Mock Drivers Summary
|
||||||
|
|
||||||
|
**TesterDriver and StreamingTesterDriver Go interfaces with TestResult/LiveReading types, four deterministic mock implementations (TreedixUSB/DP/HDMI + FNB58 streaming), and KnownDevices extended with 4 placeholder VID:PID cable tester entries**
|
||||||
|
|
||||||
|
## Performance
|
||||||
|
|
||||||
|
- **Duration:** ~12 min
|
||||||
|
- **Started:** 2026-04-10T00:00:00Z
|
||||||
|
- **Completed:** 2026-04-10T00:12:00Z
|
||||||
|
- **Tasks:** 2 (combined into single TDD cycle covering all 4 drivers)
|
||||||
|
- **Files modified:** 4
|
||||||
|
|
||||||
|
## Accomplishments
|
||||||
|
|
||||||
|
- `internal/tester` package created with TesterDriver and StreamingTesterDriver interfaces
|
||||||
|
- Four mock drivers satisfy interfaces at compile time; all 10 tests pass with -race flag clean
|
||||||
|
- KnownDevices registry now has 5 entries: 1 printer + 4 cable testers (all with TODO(hardware) datestamps)
|
||||||
|
|
||||||
|
## Task Commits
|
||||||
|
|
||||||
|
1. **RED: Failing tests for all 4 drivers** - `384ffac` (test)
|
||||||
|
2. **GREEN: driver.go + mock_drivers.go + device.go** - `11aea60` (feat)
|
||||||
|
|
||||||
|
_TDD tasks committed separately: test commit (RED) then implementation commit (GREEN)._
|
||||||
|
|
||||||
|
## Files Created/Modified
|
||||||
|
|
||||||
|
- `internal/tester/driver.go` — TesterDriver, StreamingTesterDriver interfaces; TestResult, LiveReading, CableType types; ErrNotConnected sentinel
|
||||||
|
- `internal/tester/mock_drivers.go` — MockUSBDriver, MockDPDriver, MockHDMIDriver (discrete); MockFNB58Driver (streaming, context-cancelled goroutine)
|
||||||
|
- `internal/tester/driver_test.go` — 10 tests: connect/read/disconnect for each driver, ErrNotConnected guard, stream emission count/values, pre-Connect closed channel, early Disconnect
|
||||||
|
- `internal/usb/device.go` — KnownDevices extended with dead0:0001-0004 placeholder entries for 3 Treedix testers + FNB58
|
||||||
|
|
||||||
|
## Decisions Made
|
||||||
|
|
||||||
|
- Pre-closed channel returned from `Stream()` before `Connect()` — nil channels block forever and would deadlock callers; a closed channel drains immediately with `ok=false`
|
||||||
|
- `cancelFunc` stored on `MockFNB58Driver` struct so `Disconnect()` can stop the goroutine early — directly mitigates T-05-02 (channel never closed DoS threat)
|
||||||
|
- `BaudRate: 0` for FNB58 in KnownDevices to signal HID (not serial) protocol; comment explains intent
|
||||||
|
|
||||||
|
## Deviations from Plan
|
||||||
|
|
||||||
|
None — plan executed exactly as written. Both Task 1 and Task 2 behaviors were merged into a single TDD cycle since the test file covers all 4 drivers together, but all specified behaviors are implemented and verified.
|
||||||
|
|
||||||
|
## Issues Encountered
|
||||||
|
|
||||||
|
None.
|
||||||
|
|
||||||
|
## User Setup Required
|
||||||
|
|
||||||
|
None — no external service configuration required. Mock drivers work without hardware.
|
||||||
|
|
||||||
|
## Next Phase Readiness
|
||||||
|
|
||||||
|
- `internal/tester` package is the foundation for plan 05-02 (backend HTTP endpoints for cable testing)
|
||||||
|
- Real driver implementations (plan 06) can replace mocks by implementing TesterDriver/StreamingTesterDriver
|
||||||
|
- KnownDevices VID:PIDs need updating after hardware characterization on 2026-04-13
|
||||||
|
|
||||||
|
## Self-Check: PASSED
|
||||||
|
|
||||||
|
- internal/tester/driver.go — FOUND
|
||||||
|
- internal/tester/mock_drivers.go — FOUND
|
||||||
|
- internal/tester/driver_test.go — FOUND
|
||||||
|
- commit 384ffac — FOUND
|
||||||
|
- commit 11aea60 — FOUND
|
||||||
|
- go build ./... — PASS
|
||||||
|
- go test -race ./internal/tester/... — PASS
|
||||||
|
- grep -c "dead0:" device.go — 4
|
||||||
|
|
||||||
|
---
|
||||||
|
*Phase: 05-cable-test-integration*
|
||||||
|
*Completed: 2026-04-10*
|
||||||
Loading…
Add table
Reference in a new issue