testing.md

Testing Strategy

culvert's test suite is built around deterministic register-access tests. All tests run against in-memory transport implementations; no real hardware is required at any point.

Test structure

Tests are split between inline unit tests in each src/client/ module and integration tests in tests/scdc.rs.

Unit tests (src/client/)

Each client module contains tests immediately below the code it covers. They use TestTransport, a 256-byte register array backed transport defined in src/client/test_transport.rs.

TestTransport has two constructors:

• TestTransport::new() — succeeds on all operations; used for happy-path tests.
• TestTransport::failing_after(n) — succeeds for the first n operations then returns Err(()); used to exercise every ? error branch.
• TestTransport::log() — the first 16 operations, in order, so a test can pin which registers a method reads and writes, in what order and how often.

The single generic instantiation (Scdc<TestTransport>) is intentional: using one concrete type avoids LLVM counting per-monomorphisation ? branches as uncovered, which would inflate the coverage denominator without corresponding tests.

Each register group has tests covering:

• Encoding correctness — every field of a write config maps to the correct bit position in the output register(s). One assertion per field, not per struct.
• Decoding correctness — every field of a read result is extracted from the correct bit position. Register values are crafted to isolate individual bits where necessary.
• Protocol errors — what culvert refuses produces the correct ProtocolError variant before anything is written: FFE levels above the rate's maximum. A clear of Update_0 cannot ask for RR_Test (ClearableUpdateFlags has no field for it); a test reads RR_Test and FLT_update set and clears what it read, which writes FLT_update only. Undefined values the sink reports are not errors: each undefined LtpReq nibble (0x9–0xD) decodes to LtpReq::Reserved with its raw value.
• Transport error propagation — every read and write call site has a TestTransport::failing_after(n) test that triggers failure at that exact operation and asserts the error bubbles through as ScdcError::Transport.

The register module also contains unit tests for the CedCount newtype (validity bit masking, 15-bit value preservation) and UpdateFlags::new field ordering.

codec tests decode_ced_block without a transport: the checksum valid and invalid for three and four lanes, which bytes each lane count covers, expected being the checksum that makes a block valid, the 0x00FF → 0x0100 torn read, lane 3 reported at three lanes, both warnings at once and in order, readings comparing and printing only their warnings, and, exhaustively over every checksum byte, both lane counts and lane 3 valid or not, that a mismatch comes exactly when the covered bytes do not sum to zero with expected the byte that makes them, and lane 3 is reported exactly when valid and not in use (the lane count comes from display-types' lanes(), tested there). register checks that a reading holds one warning of each kind, and that one more is a bug (debug_assert). TestTransport records a read_block as one Op::ReadBlock(reg, len), counted once by failing_after (an empty one not at all), so a test pins each multi-register method to one transaction.

Torn reads (tests/torn_reads.rs)

The tearing, as regression tests: a sink whose lane 0 counter ticks while it is read, with a checksum kept correct for its current value. Read one register at a time, 0x00FF ticking to 0x0100 reads back as 0x01FF with a ChecksumMismatch. Read as a block from a snapshotting sink, one that holds its registers still during the transaction (Block; the read_block contract leaves that to the sink), it is 0x00FF with no warning. A sweep over starting counts shows a counter ticking by one per byte never passes the checksum (a larger jump can), and a block read from that sink always returns the starting count.

Fuzzing (fuzz/)

Two cargo fuzz targets run the decoding against arbitrary register bytes: status_flags (0x40–0x42) and ced (0x50–0x58, a tenth byte picking three or four lanes). ced checks read_ced against the bytes, not against the codec it calls: each lane decoded from its own two bytes (lane 3 only with four lanes), a checksum warning exactly when the covered bytes do not sum to zero, with found the byte read and expected the byte that zeroes the sum, UnusedLaneReported exactly at three lanes with lane 3 valid, carrying its count, and no other warning, checksum first. The corpus seeds name what they cover (valid blocks for three and four lanes, a torn lane 0, an unused lane 3, a 3-lane checksum read as four lanes).

Integration tests (tests/scdc.rs)

The integration tests use SimulatedScdc, a separate infallible transport (Error = Infallible) that exercises the public API through the crate boundary. These tests confirm that the full round-trip — pre-load registers, call an Scdc method, assert on decoded output or written register state — works correctly when going through pub use re-exports.

Coverage is complementary: unit tests cover all branches and error paths; integration tests confirm end-to-end bit patterns for each register group with realistic multi-field values.

plumbob feature tests (src/client/plumbob_client.rs, tests/plumbob.rs)

When compiled with --features plumbob, two more sets of tests run:

• Unit tests call each method through the plumbob::ScdcClient trait against TestTransport and assert on register bits: every request value (and 0x9 passed on as LtpReq::Reserved), each flag clear writing only its own bit, Config_1 encoding (including FRL off), culvert's FFE-levels check, and transport errors from every method.
• End-to-end tests run plumbob's FrlTrainer through Scdc<T> against a sink simulated at the register level: FLT_ready after N reads, request nibbles posted in Status_Flags_1/2 with FLT_update, write-1-to-clear Update_0, and Config_1 starting and ending training. They cover a full training run, a rate drop, a timeout and exhausted rates ending in TMDS, FLT_no_timeout, an undefined request ignored and returned as a TrainingWarning, a 3-lane link whose unused lane 3 reports an undefined value, FRL_start and FLT_update set together (the retrain wins, and FrlStartWithRetrain is recorded), a DDC NACK mid-LTS:3 still ending in LTS:L (Config_1 back to 0, the PHY in TMDS, FLT_update cleared), a retrain resuming from no pattern, the Update_0 flags plumbob does not handle left set, and the FFE maximum limited per rate in the Config_1 byte. They check the whole chain — plumbob's sequencing, culvert's encoding, and the register bits in between.

CI's coverage run measures the default features and --features plumbob together, so the feature's module is part of the coverage ratchet.

Coverage

CI measures line coverage with cargo-llvm-cov, over the default features and the plumbob feature merged into one report. The baseline is stored in .coverage-baseline (currently 100%); CI fails if coverage drops more than 0.1% below it. New register coverage without tests will trip this.

Philosophy

Scdc<T> runs identically against simulated and real ScdcTransport implementations. A test that cannot run with an in-memory transport does not belong in this repository. Hardware is never a test dependency.