Add BDD coverage for `if name == "main"` guard in `src/cleveragents/main.py` #2214

New issue

Open

opened 2026-04-03 09:35:43 +00:00 by freemo · 0 comments

freemo commented

2026-04-03 09:35:43 +00:00

Owner

Metadata

Branch: test/coverage-main-entrypoint-guard
Commit Message: test(__main__): add BDD scenario covering if __name__ == "__main__" guard
Milestone: v3.8.0
Parent Epic: #1678

Background and Context

src/cleveragents/__main__.py contains the following entrypoint guard:

if __name__ == "__main__":
    sys.exit(run())

Existing BDD scenarios (in features/consolidated_main_modules.feature,
features/main_coverage_complete.feature, features/module_coverage.feature, and
features/coverage_maximum.feature) exercise the run() function in isolation by importing
it and calling it directly. However, the if __name__ == "__main__" branch itself — the
sys.exit(run()) statement on the guard line — is never executed as a true __main__
invocation, leaving that branch uncovered and preventing the project from reaching its ≥ 97%
coverage threshold.

The step implementations in features/steps/coverage_improvements_steps.py and
features/steps/coverage_extras_steps.py simulate the guard indirectly (by calling run()
and then manually calling mock_exit()), but this does not cause the coverage tool to mark
the if __name__ == "__main__" branch as hit.

Current Behaviour

The if __name__ == "__main__": sys.exit(run()) block in
cleveragents.__main__ is not exercised by any BDD scenario in a way that
causes the coverage tool to record the branch as covered. Running
nox -s coverage_report shows a missed branch on that guard line.

Expected Behaviour

A BDD scenario executes src/cleveragents/__main__.py as a subprocess (e.g., via
python -m cleveragents --version) so that the if __name__ == "__main__" branch is
genuinely entered and recorded as covered by the coverage tool.

Acceptance Criteria

A new Gherkin scenario (or an update to an existing relevant feature file) exercises
the if __name__ == "__main__" guard by running the module as a subprocess.
The corresponding Behave step definition launches the module via
subprocess.run(["python", "-m", "cleveragents", ...]) (or equivalent) so the
coverage tool records the branch as hit.
nox -s coverage_report no longer reports a missed branch on the guard line in
src/cleveragents/__main__.py.
All existing scenarios in features/consolidated_main_modules.feature and related
feature files continue to pass without modification.
No mock implementations are introduced into production source code.

Supporting Information

File under test: src/cleveragents/__main__.py
Relevant existing feature files: features/consolidated_main_modules.feature,
features/main_coverage_complete.feature, features/module_coverage.feature
Relevant existing step files: features/steps/main_module_steps.py,
features/steps/modules_steps.py, features/steps/coverage_improvements_steps.py
Coverage threshold: ≥ 97% (enforced by nox -s coverage_report)
Parent Epic: #1678

Subtasks

Identify the correct feature file to extend (prefer features/consolidated_main_modules.feature or features/main_coverage_complete.feature)
Write a Gherkin scenario: Scenario: __main__ guard executes sys.exit when run as a module
Implement the Behave step that runs python -m cleveragents --version as a subprocess
Verify the step correctly captures exit code and stdout
Run nox -s unit_tests — confirm new scenario passes
Run nox -s coverage_report — confirm branch is now covered and overall coverage ≥ 97%
Run nox (all default sessions) — fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit
Message in Metadata exactly (test(__main__): add BDD scenario covering if __name__ == "__main__" guard),
followed by a blank line, then additional lines providing relevant implementation details.
The commit is pushed to the remote on the branch matching the Branch in Metadata
exactly (test/coverage-main-entrypoint-guard).
The commit is submitted as a pull request to master, reviewed, and merged before
this issue is marked done.
All nox stages pass.
Coverage ≥ 97%.

Automated by CleverAgents Bot
Supervisor: Unknown | Agent: ca-new-issue-creator

## Metadata - **Branch**: `test/coverage-main-entrypoint-guard` - **Commit Message**: `test(__main__): add BDD scenario covering if __name__ == "__main__" guard` - **Milestone**: v3.8.0 - **Parent Epic**: #1678 ## Background and Context `src/cleveragents/__main__.py` contains the following entrypoint guard: ```python if __name__ == "__main__": sys.exit(run()) ``` Existing BDD scenarios (in `features/consolidated_main_modules.feature`, `features/main_coverage_complete.feature`, `features/module_coverage.feature`, and `features/coverage_maximum.feature`) exercise the `run()` function in isolation by importing it and calling it directly. However, the `if __name__ == "__main__"` branch itself — the `sys.exit(run())` statement on the guard line — is never executed as a true `__main__` invocation, leaving that branch uncovered and preventing the project from reaching its ≥ 97% coverage threshold. The step implementations in `features/steps/coverage_improvements_steps.py` and `features/steps/coverage_extras_steps.py` simulate the guard indirectly (by calling `run()` and then manually calling `mock_exit()`), but this does not cause the coverage tool to mark the `if __name__ == "__main__"` branch as hit. ## Current Behaviour The `if __name__ == "__main__": sys.exit(run())` block in `cleveragents.__main__` is not exercised by any BDD scenario in a way that causes the coverage tool to record the branch as covered. Running `nox -s coverage_report` shows a missed branch on that guard line. ## Expected Behaviour A BDD scenario executes `src/cleveragents/__main__.py` as a subprocess (e.g., via `python -m cleveragents --version`) so that the `if __name__ == "__main__"` branch is genuinely entered and recorded as covered by the coverage tool. ## Acceptance Criteria - [ ] A new Gherkin scenario (or an update to an existing relevant feature file) exercises the `if __name__ == "__main__"` guard by running the module as a subprocess. - [ ] The corresponding Behave step definition launches the module via `subprocess.run(["python", "-m", "cleveragents", ...])` (or equivalent) so the coverage tool records the branch as hit. - [ ] `nox -s coverage_report` no longer reports a missed branch on the guard line in `src/cleveragents/__main__.py`. - [ ] All existing scenarios in `features/consolidated_main_modules.feature` and related feature files continue to pass without modification. - [ ] No mock implementations are introduced into production source code. ## Supporting Information - File under test: `src/cleveragents/__main__.py` - Relevant existing feature files: `features/consolidated_main_modules.feature`, `features/main_coverage_complete.feature`, `features/module_coverage.feature` - Relevant existing step files: `features/steps/main_module_steps.py`, `features/steps/modules_steps.py`, `features/steps/coverage_improvements_steps.py` - Coverage threshold: ≥ 97% (enforced by `nox -s coverage_report`) - Parent Epic: #1678 ## Subtasks - [ ] Identify the correct feature file to extend (prefer `features/consolidated_main_modules.feature` or `features/main_coverage_complete.feature`) - [ ] Write a Gherkin scenario: `Scenario: __main__ guard executes sys.exit when run as a module` - [ ] Implement the Behave step that runs `python -m cleveragents --version` as a subprocess - [ ] Verify the step correctly captures exit code and stdout - [ ] Run `nox -s unit_tests` — confirm new scenario passes - [ ] Run `nox -s coverage_report` — confirm branch is now covered and overall coverage ≥ 97% - [ ] Run `nox` (all default sessions) — fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`test(__main__): add BDD scenario covering if __name__ == "__main__" guard`), followed by a blank line, then additional lines providing relevant implementation details. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`test/coverage-main-entrypoint-guard`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage ≥ 97%. --- **Automated by CleverAgents Bot** Supervisor: Unknown | Agent: ca-new-issue-creator

freemo added this to the v3.8.0 milestone

2026-04-03 09:35:58 +00:00

freemo added a new dependency

2026-04-03 09:37:07 +00:00

#1678 Epic: CI Execution Time Optimization — Timeouts, Concurrency, and Coverage Artifact Sharing

freemo added the

MoSCoW

Could have

label

2026-04-05 07:12:55 +00:00