feat: Add group class for better control of multi dut tests

[lucasssvaz]

Description

This pull request introduces multi-DUT (Device Under Test) synchronization support to the pytest-embedded framework, allowing users to control and coordinate multiple DUTs in parallel within tests. The main addition is the new DutGroup class, which provides a transparent, parallel proxy for running commands and assertions across multiple DUTs. The documentation and tests have been updated to reflect and validate this new functionality.

Key changes:

Multi-DUT Synchronization Feature

• Added the DutGroup class in pytest_embedded/group.py, providing a container-like proxy to run any Dut method in parallel across multiple DUTs. Special handling is included for expect and expect_exact to support both broadcast and per-DUT patterns, as well as container protocol support (indexing, iteration, etc.). (pytest-embedded/pytest_embedded/group.py)
• Exposed DutGroup in the main package API and as a class attribute on Dut for discoverability. (pytest-embedded/pytest_embedded/__init__.py, pytest-embedded/pytest_embedded/dut.py) [1] [2] [3]

Documentation Updates

• Added a new API documentation section for pytest_embedded.group and updated usage documentation to explain multi-DUT synchronization, how to use DutGroup, and its benefits for parallel test execution. (docs/apis/pytest-embedded.rst, docs/usages/expecting.rst) [1] [2] [3]

Testing

• Introduced comprehensive tests for DutGroup covering container protocol, parallel execution, broadcasting, per-DUT patterns, proxying, multi-phase synchronization, and error handling. (pytest-embedded/tests/test_base.py)

These changes significantly enhance the usability of pytest-embedded for scenarios involving multiple devices, making it easier to write robust, synchronized, and efficient multi-device tests.

Testing

Tested locally

[github-actions]

Title	Coverage	Tests	Skipped	Failures	Errors	Time
Qemu		7	0 💤	0 ❌	0 🔥	25.547s ⏱️
3.10 ARM64		109	18 💤	0 ❌	0 🔥	10m 52s ⏱️

[hfudev]

@lucasssvaz Thank you for this big improvement. I kinda like this idea. Please ping me again once the CI passed!

[lucasssvaz]

@hfudev Fixed. Looks like the rest of the errors are related to not finding USB ports on the runner.

I had the idea of creating this class while working on tests that require precise synchronization of the devices. Let me know if there is anything you would like me to change or add.

[hfudev]

Hi @lucasssvaz Thanks for the PR again.

def dut_gn(
    _fixture_classes_and_options: ClassCliOptions,
    openocd: t.Optional['OpenOcd'],
    gdb: t.Optional['Gdb'],
    app: App,
    serial: t.Union['Serial', 'LinuxSerial'] | None,
    qemu: t.Optional['Qemu'],
    wokwi: t.Optional['Wokwi'],
) -> Dut | list[Dut]:

I'm thinking probably the dut_gn here could return -> Dut | DutGroup

then it would be more IDE-friendly, but that requries a lot more refactor.

WDYT? Do you want to do it? Or I can do it in a future PR?

[lucasssvaz]

@hfudev Updated it with the requested changes. Tested it locally and everything works well. PTAL.

I don't know what are the future plans of the library so I tried doing it in the least intrusive way possible.