Manual test steps to declarative Gherkin - classification and rewrite rules

Deep reference for gherkin-from-stories ("from manual test steps" input shape). Consult when migrating manual scripts (TestRail / Qase / Xray exports) to BDD or handing a manual script to an automation engineer.

A manual test script and a Gherkin scenario describe the same behavior at different abstraction levels. Manual scripts are imperative ("click the Add to Cart button, then verify the cart count is 1"); Gherkin steps should be declarative ("the customer adds a product to their cart, then their cart shows one item"). The conversion goes wrong in a predictable way: one-for-one translation of UI mechanics produces brittle, implementation-coupled scenarios that Cucumber's own guidance warns against (https://cucumber.io/docs/bdd/better-gherkin/).

Step 1 - Classify each manual step

UI mechanics and state assertions are the two types to rewrite. Business actions are already declarative - pass them through. Setup converts to Given. Observations are typically dropped from Gherkin and lifted into step-definition implementation details.

Step 2 - Declarative-rewrite rules

The test for whether a step is too imperative: would the wording need to change if the implementation changed (e.g., the UI moved from a button to a voice command)? If yes, rewrite (https://cucumber.io/docs/bdd/better-gherkin/).

Rule R1 - Remove UI mechanics

Rule R2 - Collapse multi-step UI sequences into one business action

A manual script that says "type email; type password; click Submit" becomes one Gherkin step: When the customer signs in with valid credentials. The business action is "signing in", not "clicking, typing, clicking". The mechanics live in the step definition.

Rule R3 - Replace UI properties with observable outcomes

Rule R4 - Choose the right keyword

And and But inherit the type of the previous keyword - they are not interchangeable with Given/When/Then (https://cucumber.io/docs/gherkin/reference/).

Rule R5 - Preserve the project's existing vocabulary

Before emitting the rewrite, scan the project's existing Gherkin for the same business action. If "the customer signs in" is already used, do not introduce "the user logs in" - vocabulary drift fragments the step library and forces step-definition duplication. bdd-step-library-curator audits and consolidates that vocabulary.

Step 3 - Emit a side-by-side rewrite table

Output is a markdown table so a reviewer can confirm semantic equivalence:

The surviving rows assemble into a Scenario:

Scenario: Customer adds an in-stock product to their cart
  Given the customer is signed in
  When the customer adds SKU-001 to their cart
  Then their cart contains one item

Step 4 - Validate against project conventions

1. Check the project step library for matching existing steps; flag new steps for bdd-step-library-curator review.
2. Confirm the scenario has at most one When. Multiple Whens indicate two scenarios were collapsed; split them.
3. Lint with the project's Gherkin linter (gherkin-lint, picklesdoc, or the IDE's built-in).
4. Diff the rewrite against the manual step's expected outcome - semantic equivalence is the bar. If the manual step asserts "cart count is 1" but the rewrite asserts "cart is non-empty", that is a regression in specificity, not a successful abstraction.

Migration-specific anti-patterns

Migration-specific limitations

• Vocabulary alignment is the bottleneck, not translation. For large projects, run bdd-step-library-curator first to canonicalize vocabulary.
• Some manual steps are inherently UI-mechanical. A11y tests asserting "the Skip to main link is the first focusable element" cannot be rewritten into business language without losing the spec - pass through with R1 disabled and tag @a11y for the team to decide.
• Numerical specificity is preserved, not abstracted. "Cart count is 1" stays "cart contains one item" - not "cart is non-empty".
• Output is a draft. A human reviews the side-by-side before merging.

Sources

• Cucumber - Better Gherkin (declarative vs imperative): https://cucumber.io/docs/bdd/better-gherkin/
• Cucumber - Gherkin reference (keyword semantics): https://cucumber.io/docs/gherkin/reference/
• ISTQB glossary - test procedure (the imperative form abstracted away from): https://glossary.istqb.org/en_US/term/test-procedure