[AUTO-INF-3] TDD expected-fail listener lacks documentation and inline comments explaining tag validation logic #10336

New issue

Open

opened 2026-04-18 08:49:16 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-18 08:49:16 +00:00

Owner

Summary

The robot/tdd_expected_fail_listener.py is referenced in multiple test sessions (integration_tests, slow_integration_tests, e2e_tests) to handle TDD-style expected failures. However, the listener lacks:

Module-level documentation explaining its purpose
Inline comments explaining the tag validation logic
Clear documentation of supported tag combinations
Examples of how to use @tdd_expected_fail tags

The noxfile.py comments reference "CONTRIBUTING.md > TDD Issue Test Tags" but this makes it hard for developers to understand the listener without reading both files.

Current State

From noxfile.py:

# TDD expected-fail listener — inverts results for @tdd_expected_fail
# tagged tests and validates TDD tag combinations.
# See CONTRIBUTING.md > TDD Issue Test Tags.
tdd_listener = str(
    Path(__file__).parent / "robot" / "tdd_expected_fail_listener.py"
)

The listener is used in:

integration_tests session
slow_integration_tests session
e2e_tests session

Proposed Solution

Add comprehensive module-level docstring to robot/tdd_expected_fail_listener.py explaining:
- Purpose of the listener
- How it inverts test results for @tdd_expected_fail tags
- Tag validation rules and combinations
- Examples of valid tag usage
Add inline comments to complex validation logic
Consider adding a docstring to the listener class and key methods

Duplicate Check

Searched for: "TDD", "listener", "expected-fail", "documentation"
Results: Found TDD-related issues (#10236, #10243) but none specifically about documenting the tdd_expected_fail_listener.py module.

Automated by CleverAgents Bot
Supervisor: Test Infra Pool | Agent: test-infra-pool-supervisor

## Summary The `robot/tdd_expected_fail_listener.py` is referenced in multiple test sessions (`integration_tests`, `slow_integration_tests`, `e2e_tests`) to handle TDD-style expected failures. However, the listener lacks: 1. Module-level documentation explaining its purpose 2. Inline comments explaining the tag validation logic 3. Clear documentation of supported tag combinations 4. Examples of how to use @tdd_expected_fail tags The noxfile.py comments reference "CONTRIBUTING.md > TDD Issue Test Tags" but this makes it hard for developers to understand the listener without reading both files. ## Current State From `noxfile.py`: ```python # TDD expected-fail listener — inverts results for @tdd_expected_fail # tagged tests and validates TDD tag combinations. # See CONTRIBUTING.md > TDD Issue Test Tags. tdd_listener = str( Path(__file__).parent / "robot" / "tdd_expected_fail_listener.py" ) ``` The listener is used in: - `integration_tests` session - `slow_integration_tests` session - `e2e_tests` session ## Proposed Solution 1. Add comprehensive module-level docstring to `robot/tdd_expected_fail_listener.py` explaining: - Purpose of the listener - How it inverts test results for @tdd_expected_fail tags - Tag validation rules and combinations - Examples of valid tag usage 2. Add inline comments to complex validation logic 3. Consider adding a docstring to the listener class and key methods ### Duplicate Check Searched for: "TDD", "listener", "expected-fail", "documentation" Results: Found TDD-related issues (#10236, #10243) but none specifically about documenting the tdd_expected_fail_listener.py module. --- **Automated by CleverAgents Bot** Supervisor: Test Infra Pool | Agent: test-infra-pool-supervisor

Rows
Columns