TEST-INFRA: [test-architecture] Improve organization of Behave step definitions #4415

Open
opened 2026-04-08 12:26:03 +00:00 by HAL9000 · 0 comments
Owner

Metadata

  • Branch: refactor/test-arch/organize-behave-step-definitions
  • Commit Message: refactor(tests): reorganize Behave step definitions into feature-area subdirectories with shared modules
  • Milestone: (none — see backlog note below)
  • Parent Epic: #1678

Backlog note: This issue was discovered during autonomous operation
on milestone v3.8.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Description

The current organization of Behave step definitions in features/steps is a flat list of over 500 files. This makes it very difficult to navigate the codebase and find the steps related to a specific feature. The current structure does not follow the guidelines in CONTRIBUTING.md, which recommend organizing steps in a way that reflects the feature file structure and creating shared step modules.

Proposed Improvements

  1. Group step definitions by feature: Create subdirectories within features/steps that correspond to the major feature areas. For example, all step definitions related to plan_*.feature files could be moved into a features/steps/plan/ directory.
  2. Create shared step modules: Identify common steps that are used across multiple features and move them into modules with descriptive names, such as features/steps/shared/cli_steps.py or features/steps/shared/persistence_steps.py.

Subtasks

  • Analyze the existing step definitions to identify logical groupings based on features.
  • Create a hierarchical directory structure within features/steps that mirrors the feature areas.
  • Move the existing step definition files into the appropriate subdirectories.
  • Identify and refactor shared steps into purpose-driven modules in a features/steps/shared/ directory.
  • Update the Behave configuration to ensure that the new step organization is correctly recognized.
  • Run the full test suite to verify that all tests still pass after the refactoring.
  • Update CONTRIBUTING.md to document the new step organization guidelines.

Definition of Done

  • All step definitions are organized into subdirectories that correspond to their feature areas.
  • Shared steps are refactored into purpose-driven modules in features/steps/shared/.
  • The test suite runs successfully with the new step organization (nox -e unit_tests passes).
  • The CONTRIBUTING.md document is updated to reflect the new guidelines for organizing step definitions.
  • All nox stages pass.
  • Coverage >= 97%.

Duplicate Check

  • Search queries used: "test architecture", "step organization", "refactor steps"
  • Number of results found for each query: 0
  • Why none of the existing issues cover this specific finding: No existing issues address the organization of Behave step definitions.

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

## Metadata - **Branch**: `refactor/test-arch/organize-behave-step-definitions` - **Commit Message**: `refactor(tests): reorganize Behave step definitions into feature-area subdirectories with shared modules` - **Milestone**: *(none — see backlog note below)* - **Parent Epic**: #1678 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.8.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Description The current organization of Behave step definitions in `features/steps` is a flat list of over 500 files. This makes it very difficult to navigate the codebase and find the steps related to a specific feature. The current structure does not follow the guidelines in `CONTRIBUTING.md`, which recommend organizing steps in a way that reflects the feature file structure and creating shared step modules. ## Proposed Improvements 1. **Group step definitions by feature:** Create subdirectories within `features/steps` that correspond to the major feature areas. For example, all step definitions related to `plan_*.feature` files could be moved into a `features/steps/plan/` directory. 2. **Create shared step modules:** Identify common steps that are used across multiple features and move them into modules with descriptive names, such as `features/steps/shared/cli_steps.py` or `features/steps/shared/persistence_steps.py`. ## Subtasks - [ ] Analyze the existing step definitions to identify logical groupings based on features. - [ ] Create a hierarchical directory structure within `features/steps` that mirrors the feature areas. - [ ] Move the existing step definition files into the appropriate subdirectories. - [ ] Identify and refactor shared steps into purpose-driven modules in a `features/steps/shared/` directory. - [ ] Update the Behave configuration to ensure that the new step organization is correctly recognized. - [ ] Run the full test suite to verify that all tests still pass after the refactoring. - [ ] Update `CONTRIBUTING.md` to document the new step organization guidelines. ## Definition of Done - [ ] All step definitions are organized into subdirectories that correspond to their feature areas. - [ ] Shared steps are refactored into purpose-driven modules in `features/steps/shared/`. - [ ] The test suite runs successfully with the new step organization (`nox -e unit_tests` passes). - [ ] The `CONTRIBUTING.md` document is updated to reflect the new guidelines for organizing step definitions. - [ ] All nox stages pass. - [ ] Coverage >= 97%. ## Duplicate Check - Search queries used: "test architecture", "step organization", "refactor steps" - Number of results found for each query: 0 - Why none of the existing issues cover this specific finding: No existing issues address the organization of Behave step definitions. --- **Automated by CleverAgents Bot** Supervisor: Test Infrastructure | Agent: new-issue-creator
HAL9000 self-assigned this 2026-04-08 12:32:25 +00:00
HAL9000 added this to the v3.5.0 milestone 2026-04-08 17:42:52 +00:00
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#4415
No description provided.