Protocol YAML Roundtrip Testing

Validates that YAML protocol files generated by the web experiment designer (experiment_designer.html) are fully compatible with the MATLAB experiment runner (ProtocolParser + ProtocolRunner).

Architecture 

Web (JavaScript)                    MATLAB
─────────────────                   ──────────────────────
experiment_designer.html            ProtocolParser.m
  └─ generateV2Protocol()             └─ parse()
       (js/protocol-yaml.js)               │
       │                                    ▼
       ▼                            Parsed protocol struct
  V2 Protocol YAML ───────────────>   (version, rig, plugins,
       │                              conditions, phases)
       │                                    │
       │                                    ▼
       │                            ProtocolRunner constructor
       │                              (validates structure)
       ▼
  simpleYAMLParse()
    (js/protocol-yaml.js)

Test Coverage

Layer Test Runs in CI?
Web YAML generation + parse (v1+v2) test-protocol-roundtrip.js Yes (Node.js)
Web YAML → file generation (v1+v2) generate-roundtrip-protocol.js Yes (Node.js)
MATLAB parse + validate (v2) validate_web_protocol_roundtrip.m No (needs MATLAB license)
MATLAB ProtocolRunner construction (v2) validate_web_protocol_roundtrip.m No (needs MATLAB license)

Running Tests

Web-side CI test (no dependencies) 

cd webDisplayTools
node tests/test-protocol-roundtrip.js

Tests 130 checks across 9 suites:

  1. V1 Generate → Parse Roundtrip — full field-by-field comparison
  2. Comment-Handling Regression — comments between conditions (bug fix validation)
  3. Excluded Phases — pretrial/intertrial/posttrial with include: false
  4. Numeric Type Preservation — ints, floats, booleans parse correctly
  5. Inline Comments — comments don’t interfere with parsing
  6. V2 Simple Backlight — plugin parsing, nested params, inline comment stripping
  7. V2 Full Experiment — 9 conditions, camera + backlight plugins, multi-command conditions
  8. V2 All Possible Plugins — serial_device, class, script plugin types; nested config
  9. V2 Generate → Parse Roundtrip — full v2 generate with plugins, parse back, field-by-field

Exit code 0 = all passed, 1 = failures.

Re-generate test YAML for MATLAB 

cd webDisplayTools
node tests/generate-roundtrip-protocol.js --outdir ../maDisplayTools/tests/web_generated_patterns

Generates:

  • test_protocol_v1.yaml — V1 protocol with 3 conditions (legacy, no longer parseable by MATLAB)
  • test_protocol_manifest.json — expected values for MATLAB V1 validation
  • test_protocol_v2.yaml — V2 protocol with 3 conditions, 2 plugins (backlight + camera), multi-command conditions
  • test_protocol_v2_manifest.json — expected values for MATLAB V2 validation

The generator runs 27 V1 + 27 V2 self-verification checks.

MATLAB validation (requires MATLAB license) 

cd maDisplayTools
results = validate_web_protocol_roundtrip('v2');

Tests 35 V2 checks:

  1. ProtocolParser can parse the V2 YAML
  2. Version = 2
  3. Experiment info (name)
  4. Rig config resolved (from relative path)
  5. Arena config from rig (generation=G4.1, rows=2, cols=12)
  6. Plugins exist (2 plugins: backlight, camera)
  7. Plugin names match
  8. Experiment structure (repetitions)
  9. Number of conditions = 3
  10. Per-condition: id, num_commands, trialParams fields (duration, mode, gain) (x3)
  11. Phase includes (pretrial, intertrial, posttrial)
  12. Phase command counts (pretrial=7, intertrial=2, posttrial=4)
  13. ProtocolRunner construction (dry-run validates full pipeline)

Note: V1 is no longer supported by MATLAB ProtocolParser (v2 only). V1 web-side tests still run in CI.

Files

Web side (webDisplayTools/)

File Purpose
js/protocol-yaml.js Shared YAML parser + v1/v2 generators (dual-export module)
js/plugin-registry.js Plugin definitions + command schemas (dual-export module)
tests/test-protocol-roundtrip.js CI-ready regression test (130 checks, 9 suites)
tests/generate-roundtrip-protocol.js YAML + manifest generator for MATLAB validation (v1+v2)
tests/fixtures/v2_full_experiment_test.yaml maDisplayTools v2 example (9 conditions, camera+backlight)
tests/fixtures/v2_simple_backlight_test.yaml maDisplayTools v2 example (5 backlight-only conditions)
tests/fixtures/v2_all_possible_plugins.yaml maDisplayTools v2 example (all plugin types)

MATLAB side (maDisplayTools/)

File Purpose
tests/validate_web_protocol_roundtrip.m MATLAB validation (35 V2 checks + ProtocolRunner dry-run)
tests/web_generated_patterns/test_protocol_v1.yaml Generated V1 test YAML (legacy)
tests/web_generated_patterns/test_protocol_v2.yaml Generated V2 test YAML (3 conditions, 2 plugins)
tests/web_generated_patterns/test_protocol_manifest.json Expected values manifest (V1)
tests/web_generated_patterns/test_protocol_v2_manifest.json Expected values manifest (V2)

What to Update When Changing YAML Format

Adding new fields to V1

  1. Update generateV1Protocol() in both:
    • generate-roundtrip-protocol.js (generates files)
    • test-protocol-roundtrip.js (in-memory test)
  2. Add expected values to the testProtocol definition
  3. Add check assertions
  4. Re-generate: node tests/generate-roundtrip-protocol.js --outdir ...
  5. Update validate_web_protocol_roundtrip.m with new field checks
  6. Update manifest expected values count

Changing YAML output or parser

After modifying js/protocol-yaml.js or experiment_designer.html:

  1. Run node tests/test-protocol-roundtrip.js — catches web-side regressions (130 checks)
  2. Re-generate: node tests/generate-roundtrip-protocol.js --outdir ../maDisplayTools/tests/web_generated_patterns
  3. Run MATLAB: validate_web_protocol_roundtrip('v2') — catches cross-tool regressions (35 checks)

Adding new plugin commands

  1. Add command definition to js/plugin-registry.js
  2. Add test conditions using the new command in test-protocol-roundtrip.js
  3. Add corresponding checks in validate_web_protocol_roundtrip.m if needed
  4. Re-generate test protocols

Known Constraints

  • ProtocolRunner dry run tries to initialize hardware (PanelsController). The MATLAB test validates construction only (parse + validate), not run().
  • ProtocolParser.m and CommandExecutor.m are Lisa’s code — flagged as DO NOT MODIFY. Any incompatibilities found should be discussed before changing.
  • simpleYAMLParse is a minimal YAML parser in js/protocol-yaml.js. It handles the subset of YAML used by the experiment designer (including v2 deep nesting for plugins/params) but is not a full YAML 1.2 parser. It strips inline comments correctly.
  • V2 rig path resolution: The generated test_protocol_v2.yaml uses ../../configs/rigs/test_rig_1.yaml which resolves relative to maDisplayTools/tests/web_generated_patterns/. This rig file must exist for MATLAB validation to succeed.
This site uses Just the Docs, a documentation theme for Jekyll.