[DOCS] Python test documentation for ReadTheDocs and co-simulation message flow diagrams

[yunlishao]

Workflow: One Issue, One Branch, Three PRs

All work on one branch (e.g., docs/#122), with three PRs:

PR	Phase	Description	Prerequisite	Due
PR 1	Codebase familiarization	Read docs, understand TrafficLayer, run Python test examples, document setup issues and notes encountered.	None	Mar 2
PR 2	Python test documentation	Expand Python test docs and integrate into ReadTheDocs/Sphinx site (under Tutorials section).	PR 1 merged	Mar 23
PR 3	Message flow diagrams	Create clear per-timestep message flow diagrams (PNG + PowerPoint source in doc/). Coordinate with @YuSun-go.	PR 1 merged	Mar 23

Note: PR 2 and PR 3 can proceed in parallel after PR 1 is merged, since they are independent deliverables.

How to work

1. Create branch docs/#122 from main
2. Reference this issue in each PR (e.g., "Part of [DOCS] Python test documentation for ReadTheDocs and co-simulation message flow diagrams #122")
3. Check off the task list items below as they are completed

---

Roles

• @vkatari10 — Primary owner. Focus on Phase 1 & 2 (codebase familiarization, Python test docs). Contribute to Phase 3.
• @YuSun-go — Lead Phase 3 (synchronization/message flow diagrams). Review and support Phase 2 documentation.

---

Which module or test case is this related to?
TrafficLayer, Python test examples in tests/Python/, and co-simulation synchronization architecture documentation.

Describe the issue
The Python test examples (tests/Python/SimpleEchoClient, tests/Python/SimpleTrafficLight) have minimal documentation and are not integrated into the ReadTheDocs site. Additionally, the co-simulation message flow — clearly showing what each component sends/receives at each time step — needs to be documented with diagrams. These two efforts complement each other: understanding the Python tests requires understanding the message flow architecture.

Suggested change
This issue has progressive milestones designed to build codebase understanding while producing concrete documentation deliverables:

Phase 1: Codebase Familiarization

• Read through the existing documentation: doc/ConfigSetup.md, doc/SUMOdoc.md, README.md, and the architecture overview
• Understand how TrafficLayer orchestrates co-simulation by reading TrafficLayer/TrafficLayer/mainTrafficLayer.cpp and key helpers (CommonLib/ConfigHelper.h, CommonLib/SocketHelper.h, CommonLib/TrafficHelper.h, CommonLib/MsgHelper.h)
• Successfully run the Python test examples:
  • tests/Python/SimpleEchoClient — basic vehicle data echo
  • tests/Python/SimpleTrafficLight — traffic light data exchange
• Document any setup issues or unclear steps encountered during test execution

Phase 2: Python Test Documentation for ReadTheDocs

• Expand documentation for each Python test scenario, including:
  • What the test demonstrates (which co-simulation components are involved)
  • Prerequisites (software, network files, config)
  • How to run it
  • Expected output / what to look for
• Integrate the Python test documentation into the existing ReadTheDocs/Sphinx site (infrastructure already configured: .readthedocs.yml, doc/conf.py, doc/index.rst — the Tutorials section with tutorials/quickstart and tutorials/examples is a natural home)

Phase 3: Co-simulation Message Flow Diagrams

• Create clear message flow diagrams showing, at each time step k, what step of message is received or sent by which component. Diagrams should cover:
  • TrafficLayer ↔ Traffic Simulator (SUMO) per-step message exchange
  • TrafficLayer ↔ Application Layer (Python client) per-step message exchange
  • TrafficLayer ↔ XIL (Simulink/CarMaker) per-step synchronization
  • End-to-end flow for a complete simulation step
• Diagrams as PNG placed in doc/, with source files (PowerPoint) also tracked in the repo
• Coordinate with @YuSun-go who is updating synchronization diagrams in parallel to avoid duplication

Additional context

• The ReadTheDocs infrastructure is already set up with Sphinx (.readthedocs.yml, doc/index.rst). The Tutorials section (tutorials/quickstart, tutorials/examples) is the intended location for test/example documentation.
• Use the task list checkboxes above to track progress directly in this issue.

[yunlishao]

Additional requirement for Phase 2 — Python test framework with ground truth baselines

As part of Phase 2, please design and implement a test framework for the Python scenarios so future runs can be automatically compared against a known-good baseline. This is a prerequisite for regression testing as the TCP/IP layer evolves.

Test framework structure

tests/Python/
├── run_all_tests.py                  ← root runner: discovers and runs all scenarios
├── SimpleEchoClient/
│   ├── testplan.json                 ← declares variants for this scenario
│   ├── run_test_sumo.bat
│   ├── expected_output_sumo.json     ← ground truth for sumo variant (format flexible)
│   └── ...
├── SimpleTrafficLight/
│   ├── testplan.json
│   ├── run_test_sumo.bat
│   ├── expected_output_sumo.json
│   └── ...
└── LargeMessage/                     ← new stress test scenario (for large message testing)
    ├── testplan.json
    ├── run_test_sumo.bat
    ├── expected_output_sumo.json
    └── ...

testplan.json format

Each scenario folder contains a testplan.json declaring its variants:

{
  "variants": [
    {
      "name": "sumo",
      "bat": "run_test_sumo.bat",
      "expected_output": "expected_output_sumo.json",
      "requires": ["sumo"]
    },
    {
      "name": "vissim",
      "bat": "run_test_vissim.bat",
      "expected_output": "expected_output_vissim.json",
      "requires": ["vissim_license"]
    }
  ]
}

• requires lists tools that must be available; variants are skipped gracefully if not met
• expected_output points to the ground truth file for that variant — format and content are left to the implementer's judgement, as long as the comparison script can read it and the captured properties are meaningful enough to catch real regressions

run_all_tests.py mode flags

• --generate — run each variant and write its expected output file (establish or update a baseline)
• --verify — run and compare against existing expected output, exit nonzero on mismatch (for PR review / CI)
• --scenario <name> — run only a specific scenario folder

Deliverables

1. testplan.json for each existing scenario
2. Expected output baseline files from a known-good run
3. run_all_tests.py implementing discovery and --generate/--verify modes
4. A new LargeMessage/ stress test scenario that sends a high vehicle count to exercise large message handling, coordinated with [FEATURE] Support large message sizes with end-of-FIXS message marker in TCP/IP #87

Existing scenarios must pass --verify without modification.