TEST-INFRA: [test-architecture] Review and document BDD/Gherkin best practices #7845

Open
opened 2026-04-12 05:24:53 +00:00 by HAL9000 · 3 comments
Owner

Metadata

  • Branch: test/test-architecture-bdd-gherkin-best-practices
  • Commit Message: test(test-architecture): review and document BDD/Gherkin best practices
  • Milestone: (none — backlog)
  • Parent Epic: #5407

Background and Context

The features/ directory contains BDD/Gherkin tests written with the Behave framework. As the test suite grows, inconsistencies in language, step reuse, tagging, and documentation can accumulate, making tests harder to read, maintain, and extend. A structured review of existing BDD/Gherkin tests will establish a shared baseline of best practices for the project.

Expected Behavior

BDD/Gherkin tests in features/ follow a consistent, documented set of best practices that make them easy to read, maintain, and extend by any contributor.

Acceptance Criteria

  • All feature files use consistent, clear, and domain-aligned language (Given/When/Then).
  • Step definitions are reviewed for reusability and modularity; duplicates are consolidated.
  • Tags are used consistently to organize and filter tests (e.g., @smoke, @tdd_issue, @wip).
  • Each step definition file includes a docstring or comment documenting its purpose and usage.
  • A best-practices guide (or update to CONTRIBUTING.md) is produced summarising the conventions.

Supporting Information

  • Duplicate Check:
    • Search queries: "BDD", "Gherkin", "behave"
    • Results: 0
    • Justification: No existing issues cover a review of BDD/Gherkin best practices.
  • Related: #5407 (EPIC: Testing Infrastructure Improvements)
  • Behave docs: https://behave.readthedocs.io/

Subtasks

  • Audit all .feature files in features/ for language consistency and clarity.
  • Identify and consolidate duplicate or near-duplicate step definitions.
  • Define and apply a consistent tagging strategy across all feature files.
  • Add docstrings/comments to all step definition files documenting purpose and usage.
  • Draft a BDD/Gherkin best-practices section for CONTRIBUTING.md (or a dedicated doc).
  • Run nox (all default sessions), fix any errors.
  • Verify coverage >= 97% via nox -s coverage_report.

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, 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.
  • All nox stages pass.
  • Coverage >= 97%.

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


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

## Metadata - **Branch**: `test/test-architecture-bdd-gherkin-best-practices` - **Commit Message**: `test(test-architecture): review and document BDD/Gherkin best practices` - **Milestone**: *(none — backlog)* - **Parent Epic**: #5407 ## Background and Context The `features/` directory contains BDD/Gherkin tests written with the Behave framework. As the test suite grows, inconsistencies in language, step reuse, tagging, and documentation can accumulate, making tests harder to read, maintain, and extend. A structured review of existing BDD/Gherkin tests will establish a shared baseline of best practices for the project. ## Expected Behavior BDD/Gherkin tests in `features/` follow a consistent, documented set of best practices that make them easy to read, maintain, and extend by any contributor. ## Acceptance Criteria - [ ] All feature files use consistent, clear, and domain-aligned language (Given/When/Then). - [ ] Step definitions are reviewed for reusability and modularity; duplicates are consolidated. - [ ] Tags are used consistently to organize and filter tests (e.g., `@smoke`, `@tdd_issue`, `@wip`). - [ ] Each step definition file includes a docstring or comment documenting its purpose and usage. - [ ] A best-practices guide (or update to `CONTRIBUTING.md`) is produced summarising the conventions. ## Supporting Information - Duplicate Check: - Search queries: "BDD", "Gherkin", "behave" - Results: 0 - Justification: No existing issues cover a review of BDD/Gherkin best practices. - Related: #5407 (EPIC: Testing Infrastructure Improvements) - Behave docs: https://behave.readthedocs.io/ ## Subtasks - [ ] Audit all `.feature` files in `features/` for language consistency and clarity. - [ ] Identify and consolidate duplicate or near-duplicate step definitions. - [ ] Define and apply a consistent tagging strategy across all feature files. - [ ] Add docstrings/comments to all step definition files documenting purpose and usage. - [ ] Draft a BDD/Gherkin best-practices section for `CONTRIBUTING.md` (or a dedicated doc). - [ ] Run `nox` (all default sessions), fix any errors. - [ ] Verify coverage >= 97% via `nox -s coverage_report`. ## 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, 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. - All nox stages pass. - Coverage >= 97%. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.2.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: Test Infrastructure | Agent: new-issue-creator
Author
Owner

Verified — Test infrastructure task: BDD/Gherkin best practices documentation. MoSCoW: Could-have. Priority: Low.


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

✅ **Verified** — Test infrastructure task: BDD/Gherkin best practices documentation. MoSCoW: Could-have. Priority: Low. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Author
Owner

Verified — Test infrastructure task: BDD/Gherkin best practices documentation. MoSCoW: Could-have. Priority: Low.


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

✅ **Verified** — Test infrastructure task: BDD/Gherkin best practices documentation. MoSCoW: Could-have. Priority: Low. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Author
Owner

Verified — Test infrastructure task: BDD/Gherkin best practices documentation. MoSCoW: Could-have. Priority: Low.


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

✅ **Verified** — Test infrastructure task: BDD/Gherkin best practices documentation. MoSCoW: Could-have. Priority: Low. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
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#7845
No description provided.