# TDR-0001: E27 Test Evidence Capture Contract

Status: Accepted  
Date: 2025-12-23  
Applies to: E27 backend testing (offline and live)

## Context

E27 protocol testing involves multiple layers:
- link-layer framing and CRC
- presentation-layer encryption and padding
- JSON application semantics
- backend state transitions

Past failures (e.g. authorization decryption issues) demonstrated that
simple pass/fail tests are insufficient. When a test fails, sufficient
evidence must be captured to diagnose the root cause **without re-running
live hardware**.

A standardized test evidence capture contract is required to:
- make failures diagnosable
- prevent ad-hoc debug logging
- ensure consistency across offline and live tests
- support regression analysis

## Decision

All E27 tests MUST emit a structured test record capturing:

1. Test metadata and execution context
2. Session and authorization context
3. Per-request/per-response wire-level details
4. Decryption attempt details (including key selection and magic validation)
5. Parsed JSON and API-level validation results
6. Semantic outputs and backend dispatch outcomes
7. Explicit assertion and failure classification

This capture contract applies to:
- offline vector tests
- emulator-based tests
- live panel tests

## Rationale

E27 failures are often protocol-semantic rather than algorithmic.
Diagnosing issues such as:
- incorrect pad length
- wrong encryption key usage
- framing or CRC errors
requires precise intermediate artifacts.

A mandatory capture contract:
- eliminates ambiguity during failure analysis
- allows comparison between passing and failing runs
- decouples diagnosis from live panel availability

## Consequences

Positive:
- Failures are self-diagnosing
- Reduced need for repeated live testing
- Consistent artifacts for CI and manual inspection

Tradeoffs:
- Increased verbosity in test artifacts
- Slight additional complexity in test helpers

Explicitly not doing:
- Dumping full decrypted payloads by default
- Logging secrets or credentials

## References

- ADR: E27 API Message Layer Architecture
- E27 API Comms Protocol
- Dealer API JSON Interface (HelpDealerAPI_UL)
