BUG: [test-architecture] AmbiguousStep errors — 553 duplicate Behave step patterns across features/steps/ #1806

New issue

Open

opened 2026-04-02 23:53:22 +00:00 by freemo · 1 comment

freemo commented

2026-04-02 23:53:22 +00:00

Owner

Metadata

Branch: fix/behave-ambiguous-step-553-patterns
Commit Message: fix(tests): eliminate 553 ambiguous Behave step patterns in features/steps/
Milestone: v3.8.0
Parent Epic: #739

Problem

A static analysis of features/steps/ (770 step modules, ~25 316 total step definitions) reveals 553 non-empty cross-file ambiguous step patterns — step text strings registered by @given, @when, or @then decorators that are defined in more than one step module. When Behave loads all step modules simultaneously, it cannot deterministically resolve which implementation to invoke, raising an AmbiguousStep error at runtime.

This is a significant regression from the 114 patterns documented in #1609 (v3.7.0). The collision count has grown nearly 5× since that issue was filed, indicating that new step files are being added without enforcing the naming convention.

Worst offenders (by number of conflicting files)

Pattern	Conflicting files
`'I execute the '`	30
`'the '`	19
`'pec I invoke '`	17
`'a project '`	14
`'I record a '`	13
`'I have added '`	3
`'the dependencies for '`	2
`'I remove '`	2
`'the error should mention '`	2
`'I create a '`	2
… (543 more)	…

Root Cause

Step text strings are too generic and are written in isolation without a project-wide naming convention being enforced at the CI level. Many step files already acknowledge this and use ad-hoc prefixes (e.g., m3 smoke, tdd1141, sv, pfg-, idx, errcov, sysdiag_), but the workarounds are inconsistent and there is no automated gate preventing new collisions from being introduced.

Subtasks

Run behave --dry-run and capture the full list of AmbiguousStep errors
Audit all 553 ambiguous patterns and group them by domain (plan, actor, tool, resource, project, a2a, etc.)
Define (or enforce the existing) project-wide step-naming convention: every step pattern must be prefixed with a short, unique domain token
Add a nox -e lint hook or standalone script that statically detects duplicate step patterns and fails the build — preventing future regressions
Update CONTRIBUTING.md with the step-naming convention and a reference to the lint gate
Rename all 553 ambiguous step patterns in both the step files and their corresponding .feature files
Verify nox -e unit_tests passes with zero AmbiguousStep errors
Verify nox -e coverage_report still reports ≥ 97%
Run full nox suite and confirm all sessions pass

Definition of Done

Zero AmbiguousStep errors reported by behave --dry-run
A CI lint gate (nox session or pre-commit hook) prevents future ambiguous step registrations
CONTRIBUTING.md documents the step-naming convention
All nox stages pass
Coverage ≥ 97%
PR merged and this issue closed

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

## Metadata - **Branch**: `fix/behave-ambiguous-step-553-patterns` - **Commit Message**: `fix(tests): eliminate 553 ambiguous Behave step patterns in features/steps/` - **Milestone**: v3.8.0 - **Parent Epic**: #739 ## Problem A static analysis of `features/steps/` (770 step modules, ~25 316 total step definitions) reveals **553 non-empty cross-file ambiguous step patterns** — step text strings registered by `@given`, `@when`, or `@then` decorators that are defined in more than one step module. When Behave loads all step modules simultaneously, it cannot deterministically resolve which implementation to invoke, raising an `AmbiguousStep` error at runtime. This is a significant regression from the 114 patterns documented in #1609 (v3.7.0). The collision count has grown nearly **5× since that issue was filed**, indicating that new step files are being added without enforcing the naming convention. ### Worst offenders (by number of conflicting files) | Pattern | Conflicting files | |---|---| | `'I execute the '` | 30 | | `'the '` | 19 | | `'pec I invoke '` | 17 | | `'a project '` | 14 | | `'I record a '` | 13 | | `'I have added '` | 3 | | `'the dependencies for '` | 2 | | `'I remove '` | 2 | | `'the error should mention '` | 2 | | `'I create a '` | 2 | | … (543 more) | … | ### Root Cause Step text strings are too generic and are written in isolation without a project-wide naming convention being enforced at the CI level. Many step files already acknowledge this and use ad-hoc prefixes (e.g., `m3 smoke`, `tdd1141`, `sv`, `pfg-`, `idx`, `errcov`, `sysdiag_`), but the workarounds are inconsistent and there is no automated gate preventing new collisions from being introduced. ## Subtasks - [ ] Run `behave --dry-run` and capture the full list of `AmbiguousStep` errors - [ ] Audit all 553 ambiguous patterns and group them by domain (plan, actor, tool, resource, project, a2a, etc.) - [ ] Define (or enforce the existing) project-wide step-naming convention: every step pattern must be prefixed with a short, unique domain token - [ ] Add a `nox -e lint` hook or standalone script that statically detects duplicate step patterns and fails the build — preventing future regressions - [ ] Update `CONTRIBUTING.md` with the step-naming convention and a reference to the lint gate - [ ] Rename all 553 ambiguous step patterns in both the step files and their corresponding `.feature` files - [ ] Verify `nox -e unit_tests` passes with zero `AmbiguousStep` errors - [ ] Verify `nox -e coverage_report` still reports ≥ 97% - [ ] Run full `nox` suite and confirm all sessions pass ## Definition of Done - [ ] Zero `AmbiguousStep` errors reported by `behave --dry-run` - [ ] A CI lint gate (nox session or pre-commit hook) prevents future ambiguous step registrations - [ ] `CONTRIBUTING.md` documents the step-naming convention - [ ] All nox stages pass - [ ] Coverage ≥ 97% - [ ] PR merged and this issue closed --- **Automated by CleverAgents Bot** Supervisor: Unknown | Agent: ca-new-issue-creator

freemo added this to the v3.8.0 milestone

2026-04-02 23:53:28 +00:00

freemo added a new dependency

2026-04-02 23:56:40 +00:00

#739 Epic: E2E Testing Suite for Acceptance Criteria and Workflow Examples

freemo referenced this issue

2026-04-02 23:57:26 +00:00

TEST-INFRA: [test-architecture] Fix AmbiguousStep error in Behave steps #1847

freemo commented

2026-04-02 23:57:32 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: MoSCoW/Could Have — CI/test infrastructure improvement.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: MoSCoW/Could Have — CI/test infrastructure improvement. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added the

MoSCoW

Could have

label

2026-04-02 23:57:33 +00:00

freemo referenced this issue

2026-04-03 00:01:24 +00:00

TEST-INFRA: [test-architecture] AmbiguousStep error in Behave step definitions #1864

freemo referenced this issue

2026-04-03 00:10:35 +00:00

TEST-INFRA: [test-architecture] Refactor duplicated step definitions #1903