imdd_silas/TEST_TODO.md

# Test TODO

This file is the current backlog for building out the MATLAB test suite.
It should reflect the repository state now, not the original plan.

## Current Status

Fast profile status:

- `run_all_tests('profile','fast')`
- latest verified result: `Passed: 82 | Failed: 0 | Incomplete: 0`
- explicit placeholder tests remaining: `62`

Mandatory workflow for every future test-writing session:

1. Read the target class implementation in `Classes/...` before writing or changing tests.
2. Read the current placeholder or existing test in `Tests/...`.
3. Replace or extend the existing test. Do not create duplicate test files.
4. Use the existing `matlab.unittest` framework and extend `IMDDTestCase`.
5. Tag new tests with `TestTags`.
6. Run the relevant test entrypoint after implementation.
7. Do not consider the task complete until the test run result is checked.

## Completed Base Tests

These are already implemented and verified in the fast profile:

- `Classes/00_signals/Signal.m` -> `Tests/00_signals/Signal_test.m`
- `Classes/00_signals/Informationsignal.m` -> `Tests/00_signals/Informationsignal_test.m`
- `Classes/00_signals/Electricalsignal.m` -> `Tests/00_signals/Electricalsignal_test.m`
- `Classes/00_signals/Opticalsignal.m` -> `Tests/00_signals/Opticalsignal_test.m`
- `Classes/01_transmit/PAMmapper.m` -> `Tests/01_transmit/PAMmapper_test.m`
- `Classes/01_transmit/PAMsource.m` -> `Tests/01_transmit/PAMsource_test.m`
- `Classes/01_transmit/Signalgenerator.m` -> `Tests/01_transmit/Signalgenerator_test.m`
- `Classes/01_transmit/Pulseformer.m` -> `Tests/01_transmit/Pulseformer_test.m`
- `Classes/02_etc/Amplifier.m` -> `Tests/02_etc/Amplifier_test.m`
- `Classes/02_etc/Filter.m` -> `Tests/02_etc/Filter_test.m`
- `Classes/02_optical/Fiber.m` -> `Tests/02_optical/Fiber_test.m`
- `Classes/02_optical/EML.m` -> `Tests/02_optical/EML_test.m`
- `Classes/02_optical/Optical_Multiplex.m` -> `Tests/02_optical/Optical_Multiplex_test.m`
- `Classes/02_optical/Optical_Demultiplex.m` -> `Tests/02_optical/Optical_Demultiplex_test.m`
- `Classes/02_optical/DP_Fiber.m` -> `Tests/02_optical/DP_Fiber_test.m`
- `Classes/03_receive/Photodiode.m` -> `Tests/03_receive/Photodiode_test.m`
- `Classes/03_receive/Scope.m` -> `Tests/03_receive/Scope_test.m`
- `Classes/04_DSP/TransmissionPerformance.m` -> `Tests/04_DSP/TransmissionPerformance_test.m`
- `Classes/04_DSP/Equalizer/FFE.m` -> `Tests/04_DSP/Equalizer/FFE_test.m`
- `Classes/04_DSP/Sequence Detection/MLSE.m` -> `Tests/04_DSP/Sequence Detection/MLSE_test.m`
- `Classes/04_DSP/Timing Recovery/Timing_Recovery.m` -> `Tests/04_DSP/Timing Recovery/T_04_DSP_Timing_Recovery_Timing_Recovery_test.m`

Notes:

- There are multiple `Timing_Recovery` class names in the repo, so the implemented base-class test currently uses the disambiguated file name:
  `Tests/04_DSP/Timing Recovery/T_04_DSP_Timing_Recovery_Timing_Recovery_test.m`

## Integration Tests

These are the current end-to-end regression guards:

- `Tests/integration/IMDD_base_system_minimal_integration_test.m`
- `Tests/integration/IMDD_base_system_no_impairment_integration_test.m`
- `Tests/integration/IMDD_base_system_impairment_monotonicity_integration_test.m`
- `Tests/integration/WDM_mux_demux_optical_chain_integration_test.m`
- `Tests/integration/WDM_end_to_end_two_channel_receiver_integration_test.m`

Current integration focus:

- refactor the duplicated reduced IM/DD workflow setup into shared integration helpers
- tighten the IM/DD baseline naming and thresholds so the physical intent is honest
- strengthen the WDM optical-chain and end-to-end receiver fixtures into harder regression guards
- keep all integration fixtures deterministic and small enough to remain reviewable

## Remaining Core Tests

Highest-value unfinished unit tests to implement next:

1. `Classes/02_optical/Polarization_Controller.m`
   `Tests/02_optical/Polarization_Controller_test.m`
   Focus:
   - deterministic transform behavior
   - shape preservation

2. `Classes/01_transmit/AWG.m`
   `Tests/01_transmit/AWG_test.m`
   Focus:
   - DAC-like resampling and quantization behavior
   - length and sampling-rate invariants
   - deterministic small fixtures

Follow-up around the WDM integration fixtures:

- `Classes/01_transmit/AWG.m`
- `Classes/02_optical/EML.m`
- `Classes/02_optical/Polarization_Controller.m`
- `Classes/02_optical/DP_Fiber.m`
- `Classes/02_optical/Optical_Multiplex.m`
- `Classes/02_optical/Optical_Demultiplex.m`
- `Classes/03_receive/Photodiode.m`

These should be revisited together when the WDM integration tests are tightened.

Immediate integration refactor backlog:

1. Extract shared reduced IM/DD integration helpers
   Targets:
   - `Tests/integration/IMDD_base_system_minimal_integration_test.m`
   - `Tests/integration/IMDD_base_system_no_impairment_integration_test.m`
   - `Tests/integration/IMDD_base_system_impairment_monotonicity_integration_test.m`
   Goal:
   - remove duplicated reduced-workflow builders
   - keep assertions local to each test file

2. Revisit the "no impairment" IM/DD fixture
   Target:
   - `Tests/integration/IMDD_base_system_no_impairment_integration_test.m`
   Goal:
   - ensure the name, comments, and thresholds reflect the actual physical regime

3. Harden the WDM optical-chain regression guards
   Targets:
   - `Tests/integration/WDM_mux_demux_optical_chain_integration_test.m`
   - `Tests/integration/WDM_end_to_end_two_channel_receiver_integration_test.m`
   Goal:
   - improve channel-separation assertions
   - add propagated-chain checks where stable
   - avoid brittle waveform snapshots

## Next DSP Layer

After the items above, continue with these:

- `Classes/04_DSP/Coding/Duobinary.m`
  `Tests/04_DSP/Coding/Duobinary_test.m`
- `Classes/04_DSP/Coding/MRDS_coding.m`
  `Tests/04_DSP/Coding/MRDS_coding_test.m`
- `Classes/04_DSP/Sequence Detection/MLSE_viterbi.m`
  `Tests/04_DSP/Sequence Detection/MLSE_viterbi_test.m`
- `Classes/04_DSP/Sequence Detection/MLSE_new.m`
  `Tests/04_DSP/Sequence Detection/MLSE_new_test.m`
- `Classes/04_DSP/Timing Recovery/Time_Shifter.m`
  `Tests/04_DSP/Timing Recovery/Time_Shifter_test.m`
- `Classes/04_DSP/Timing Recovery/Godard_Timing_Recovery.m`
  `Tests/04_DSP/Timing Recovery/Godard_Timing_Recovery_test.m`
- `Classes/04_DSP/Timing Recovery/MaxVar_Timing_Recovery.m`
  `Tests/04_DSP/Timing Recovery/MaxVar_Timing_Recovery_test.m`

Then move on to the remaining equalizer variants:

- `EQ.m`
- `EQ_copy.m`
- `EQ_silas*.m`
- `FFE_*`
- `ML_MLSE*.m`
- `Postfilter.m`
- `VNLE.m`

## Lower Priority Areas

Leave these for later unless a current task depends on them:

- `Classes/Warehouse_class/*`
- `Classes/DataBaseHandler/*`
- template/example classes like `class_template`

## Excluded From Automated Testing

Do not create or run automated tests for lab device classes in this repository.

Excluded area:

- `Classes/05_Lab/*`

Reason:

- the device IPs are reachable in this environment
- executing these classes can change instrument set points
- this can interfere with external or ongoing experiments

Rule for future sessions:

- do not implement `Tests/05_Lab/*`
- do not run files that communicate with lab devices
- do not add these classes back into the active TODO backlog unless explicitly requested by the user for a controlled setup

## Session Prompt Checklist

Every future agent prompt should include these requirements:

- read the class implementation first
- read the current test file second
- implement the test in the existing file
- prefer deterministic synthetic fixtures
- avoid plotting and hardware unless required
- never run or implement `05_Lab` tests in normal agent sessions
- run `run_all_tests('profile','fast')` after implementation
- report the changed files and the verification result