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

Open
opened 2026-04-03 00:10:35 +00:00 by freemo · 1 comment
Owner

Metadata

  • Branch: refactor/test-arch-deduplicate-step-definitions
  • Commit Message: refactor(tests): consolidate duplicated Behave step definitions into shared purpose-driven modules
  • Milestone: v3.2.0
  • Parent Epic: #1678

Background and Context

The test suite contains a number of duplicated step definitions. This is a violation of the BDD guideline that says to "Group new steps with related ones." and "Keep shared steps in purpose-driven modules."

The duplicated steps are defined in multiple files, often with the same implementation. This makes the test suite harder to maintain, as changes to a step may need to be made in multiple places. It also increases the risk of inconsistencies between tests.

It is recommended that the team:

  1. Create a set of shared step definition files for common steps that are used across multiple features.
  2. Refactor the existing step definitions to remove duplication and move shared steps to the appropriate shared files.
  3. Establish a clear process for adding new steps to ensure that they are added to the correct file and that duplication is avoided.

Current Behavior

Step definitions are duplicated across multiple files in the features/steps/ directory. The same step pattern is implemented more than once, often with identical or near-identical logic. This violates the BDD organization guidelines in CONTRIBUTING.md and causes AmbiguousStep errors at runtime when Behave matches more than one implementation for the same pattern.

Expected Behavior

Each step definition exists in exactly one location. Shared steps used across multiple features live in clearly named, purpose-driven shared modules. Feature-specific steps live in correspondingly named step definition files. No step pattern is registered more than once.

Acceptance Criteria

  • All duplicated step definitions have been identified via audit
  • Each duplicated step is consolidated into a single, canonical location (shared module or feature-specific file, as appropriate)
  • No AmbiguousStep errors are raised when running the Behave test suite
  • All existing tests continue to pass after the refactor (nox -s unit_tests)
  • Coverage remains ≥ 97% after the refactor
  • CONTRIBUTING.md BDD organization guidelines are followed for all step placements

Supporting Information

  • CONTRIBUTING.md BDD Test Organization Guidelines: "Group new steps with related ones." and "Keep shared steps in purpose-driven modules."
  • Related issues: #1806 (AmbiguousStep errors — 553 duplicate Behave step patterns), #1864, #1847

Subtasks

  • Audit all step definition files in features/steps/ and identify all duplicated step patterns
  • Categorize duplicated steps as either shared (used across multiple features) or feature-specific
  • Create or extend shared step definition modules for common steps used across multiple features
  • Move feature-specific duplicated steps into their corresponding feature step file
  • Remove all duplicate step registrations, leaving only the canonical implementation in each case
  • Run nox -s unit_tests to confirm no AmbiguousStep errors and all tests pass
  • Run full nox suite and confirm all sessions pass
  • Verify coverage ≥ 97% via nox -s coverage_report
  • Update CONTRIBUTING.md if needed to reinforce the process for adding new steps

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • No duplicated step definitions remain in the test suite.
  • No AmbiguousStep errors are raised by Behave.
  • All nox stages pass.
  • Coverage ≥ 97%.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

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

## Metadata - **Branch**: `refactor/test-arch-deduplicate-step-definitions` - **Commit Message**: `refactor(tests): consolidate duplicated Behave step definitions into shared purpose-driven modules` - **Milestone**: v3.2.0 - **Parent Epic**: #1678 ## Background and Context The test suite contains a number of duplicated step definitions. This is a violation of the BDD guideline that says to "Group new steps with related ones." and "Keep shared steps in purpose-driven modules." The duplicated steps are defined in multiple files, often with the same implementation. This makes the test suite harder to maintain, as changes to a step may need to be made in multiple places. It also increases the risk of inconsistencies between tests. It is recommended that the team: 1. Create a set of shared step definition files for common steps that are used across multiple features. 2. Refactor the existing step definitions to remove duplication and move shared steps to the appropriate shared files. 3. Establish a clear process for adding new steps to ensure that they are added to the correct file and that duplication is avoided. ## Current Behavior Step definitions are duplicated across multiple files in the `features/steps/` directory. The same step pattern is implemented more than once, often with identical or near-identical logic. This violates the BDD organization guidelines in `CONTRIBUTING.md` and causes `AmbiguousStep` errors at runtime when Behave matches more than one implementation for the same pattern. ## Expected Behavior Each step definition exists in exactly one location. Shared steps used across multiple features live in clearly named, purpose-driven shared modules. Feature-specific steps live in correspondingly named step definition files. No step pattern is registered more than once. ## Acceptance Criteria - [ ] All duplicated step definitions have been identified via audit - [ ] Each duplicated step is consolidated into a single, canonical location (shared module or feature-specific file, as appropriate) - [ ] No `AmbiguousStep` errors are raised when running the Behave test suite - [ ] All existing tests continue to pass after the refactor (`nox -s unit_tests`) - [ ] Coverage remains ≥ 97% after the refactor - [ ] `CONTRIBUTING.md` BDD organization guidelines are followed for all step placements ## Supporting Information - `CONTRIBUTING.md` BDD Test Organization Guidelines: "Group new steps with related ones." and "Keep shared steps in purpose-driven modules." - Related issues: #1806 (AmbiguousStep errors — 553 duplicate Behave step patterns), #1864, #1847 ## Subtasks - [ ] Audit all step definition files in `features/steps/` and identify all duplicated step patterns - [ ] Categorize duplicated steps as either shared (used across multiple features) or feature-specific - [ ] Create or extend shared step definition modules for common steps used across multiple features - [ ] Move feature-specific duplicated steps into their corresponding feature step file - [ ] Remove all duplicate step registrations, leaving only the canonical implementation in each case - [ ] Run `nox -s unit_tests` to confirm no `AmbiguousStep` errors and all tests pass - [ ] Run full `nox` suite and confirm all sessions pass - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Update `CONTRIBUTING.md` if needed to reinforce the process for adding new steps ## Definition of Done This issue is complete when: - [ ] All subtasks above are completed and checked off. - [ ] No duplicated step definitions remain in the test suite. - [ ] No `AmbiguousStep` errors are raised by Behave. - [ ] All nox stages pass. - [ ] Coverage ≥ 97%. - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. --- **Automated by CleverAgents Bot** Supervisor: Test Infrastructure | Agent: ca-new-issue-creator
freemo added this to the v3.2.0 milestone 2026-04-03 00:11:03 +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
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#1903
No description provided.