TEST-INFRA: [test-architecture] Organize non-step-definition Python files in features/steps #2204

Open
opened 2026-04-03 09:30:18 +00:00 by freemo · 0 comments
Owner

Metadata

  • Branch: chore/test-arch-organize-step-helper-files
  • Commit Message: chore(test-infra): relocate non-step-definition helper modules out of features/steps/
  • Milestone: v3.8.0
  • Parent Epic: #1678

Background and Context

The features/steps/ directory is intended exclusively for Behave step definition files (i.e., Python modules that register @given, @when, @then decorated functions). However, several non-step-definition Python files have accumulated in this directory:

  • features/steps/_inheritance_test_helpers.py — shared helpers for resource-type-inheritance BDD step files
  • features/steps/_uko_l2_test_helpers.py — shared helpers for UKO Layer 2 BDD step files
  • features/steps/decomposition_test_helpers.py — factory functions and fixtures for decomposition BDD step files
  • features/steps/provider_stub_utils.py — shared provider stub utilities for Behave tests
  • features/steps/uko_indexer_common.py — shared helpers, constants, and Background steps for UKO Indexer tests

These files are utility/helper modules, not step definition files. Placing them in features/steps/ violates the single-purpose directory principle from CONTRIBUTING.md: "Each directory should have a clear, single purpose — do not mix concerns." The features/steps/ directory should contain only step definition files.

Expected Behavior

All non-step-definition Python helper and utility modules should be relocated to an appropriate subdirectory (e.g., features/steps/helpers/ or a dedicated features/support/ directory), and all imports in the step definition files that reference them should be updated accordingly. The features/steps/ directory should contain only files that register Behave step definitions.

Acceptance Criteria

  • All five non-step-definition files are removed from features/steps/ and placed in a clearly named subdirectory (e.g., features/steps/helpers/)
  • All step definition files that import from the relocated modules are updated with correct import paths
  • No Behave step registration errors or import errors occur after the move
  • The full Behave test suite passes without regressions (nox -s behave or equivalent)
  • Coverage remains >= 97%

Supporting Information

Files to relocate:

  • features/steps/_inheritance_test_helpers.py
  • features/steps/_uko_l2_test_helpers.py
  • features/steps/decomposition_test_helpers.py
  • features/steps/provider_stub_utils.py
  • features/steps/uko_indexer_common.py

Related issues: #1795 (organize Behave feature files into subdirectories), #1902 (name step files after their feature), #1965 (naming convention for helper files)

Subtasks

  • Audit all five non-step-definition files and confirm they contain no @given/@when/@then step registrations (except uko_indexer_common.py which does contain steps — handle accordingly)
  • Create features/steps/helpers/ subdirectory (or features/support/ as appropriate) with an __init__.py
  • Move the four pure-helper files (_inheritance_test_helpers.py, _uko_l2_test_helpers.py, decomposition_test_helpers.py, provider_stub_utils.py) to the new subdirectory
  • For uko_indexer_common.py (which registers Behave steps): either keep it in features/steps/ with a rename to uko_indexer_common_steps.py, or extract its non-step helpers into the helpers subdirectory and leave only the step registrations in features/steps/
  • Update all import statements in step definition files that reference the relocated modules
  • Run nox -s behave (or equivalent) and confirm no import errors or step registration failures
  • Run full nox suite and confirm all sessions pass
  • Verify coverage >= 97% via nox -s coverage_report

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • All non-step-definition helper files have been relocated out of features/steps/ into an appropriate subdirectory.
  • All imports in step definition files are updated and correct.
  • The Behave test suite runs without errors or regressions.
  • 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: Unknown | Agent: ca-new-issue-creator

## Metadata - **Branch**: `chore/test-arch-organize-step-helper-files` - **Commit Message**: `chore(test-infra): relocate non-step-definition helper modules out of features/steps/` - **Milestone**: v3.8.0 - **Parent Epic**: #1678 ## Background and Context The `features/steps/` directory is intended exclusively for Behave step definition files (i.e., Python modules that register `@given`, `@when`, `@then` decorated functions). However, several non-step-definition Python files have accumulated in this directory: - `features/steps/_inheritance_test_helpers.py` — shared helpers for resource-type-inheritance BDD step files - `features/steps/_uko_l2_test_helpers.py` — shared helpers for UKO Layer 2 BDD step files - `features/steps/decomposition_test_helpers.py` — factory functions and fixtures for decomposition BDD step files - `features/steps/provider_stub_utils.py` — shared provider stub utilities for Behave tests - `features/steps/uko_indexer_common.py` — shared helpers, constants, and Background steps for UKO Indexer tests These files are utility/helper modules, not step definition files. Placing them in `features/steps/` violates the single-purpose directory principle from `CONTRIBUTING.md`: *"Each directory should have a clear, single purpose — do not mix concerns."* The `features/steps/` directory should contain only step definition files. ## Expected Behavior All non-step-definition Python helper and utility modules should be relocated to an appropriate subdirectory (e.g., `features/steps/helpers/` or a dedicated `features/support/` directory), and all imports in the step definition files that reference them should be updated accordingly. The `features/steps/` directory should contain only files that register Behave step definitions. ## Acceptance Criteria - [ ] All five non-step-definition files are removed from `features/steps/` and placed in a clearly named subdirectory (e.g., `features/steps/helpers/`) - [ ] All step definition files that import from the relocated modules are updated with correct import paths - [ ] No Behave step registration errors or import errors occur after the move - [ ] The full Behave test suite passes without regressions (`nox -s behave` or equivalent) - [ ] Coverage remains >= 97% ## Supporting Information Files to relocate: - `features/steps/_inheritance_test_helpers.py` - `features/steps/_uko_l2_test_helpers.py` - `features/steps/decomposition_test_helpers.py` - `features/steps/provider_stub_utils.py` - `features/steps/uko_indexer_common.py` Related issues: #1795 (organize Behave feature files into subdirectories), #1902 (name step files after their feature), #1965 (naming convention for helper files) ## Subtasks - [ ] Audit all five non-step-definition files and confirm they contain no `@given`/`@when`/`@then` step registrations (except `uko_indexer_common.py` which does contain steps — handle accordingly) - [ ] Create `features/steps/helpers/` subdirectory (or `features/support/` as appropriate) with an `__init__.py` - [ ] Move the four pure-helper files (`_inheritance_test_helpers.py`, `_uko_l2_test_helpers.py`, `decomposition_test_helpers.py`, `provider_stub_utils.py`) to the new subdirectory - [ ] For `uko_indexer_common.py` (which registers Behave steps): either keep it in `features/steps/` with a rename to `uko_indexer_common_steps.py`, or extract its non-step helpers into the helpers subdirectory and leave only the step registrations in `features/steps/` - [ ] Update all import statements in step definition files that reference the relocated modules - [ ] Run `nox -s behave` (or equivalent) and confirm no import errors or step registration failures - [ ] Run full `nox` suite and confirm all sessions pass - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - [ ] All subtasks above are completed and checked off. - [ ] All non-step-definition helper files have been relocated out of `features/steps/` into an appropriate subdirectory. - [ ] All imports in step definition files are updated and correct. - [ ] The Behave test suite runs without errors or regressions. - [ ] 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: Unknown | Agent: ca-new-issue-creator
freemo added this to the v3.8.0 milestone 2026-04-03 09:30:37 +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#2204
No description provided.