manual-step-to-gherkin

Overview

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 looks mechanical but goes wrong in a predictable way: junior automation engineers translate UI mechanics one-for-one and produce brittle, implementation-coupled scenarios that Cucumber's own guidance explicitly warns against (https://cucumber.io/docs/bdd/better-gherkin/).

This skill is the rules-based translator that takes a manual step and emits the declarative Gherkin equivalent. It is the handoff artifact between manual QA and automation engineers - and it is also the migration tool when a team moves from manual-script-driven QA (TestRail / Qase / Xray manual cases) to BDD.

When to use

• A manual tester has written a script (or a TestRail / Qase / Xray case) and is handing it off to an automation engineer.
• A team is migrating their existing manual case library to Cucumber / SpecFlow / Reqnroll / Behave.
• A test-management tool (TestRail, Qase, Xray) needs its imperative steps re-expressed as Gherkin for a BDD pipeline.
• A reviewer is auditing existing Gherkin for declarative-vs-imperative violations.

Do not use this skill when:

• The starting point is a user story, not an existing manual step - go to gherkin-from-stories.
• The starting point is acceptance criteria - go to acceptance-test-from-criteria.
• The team has explicitly chosen imperative Gherkin (rare; some legacy teams). The skill defaults to declarative per Cucumber's guidance.

Step 1 - Classify the manual step

Read the step and tag it:

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

Step 2 - Apply declarative-rewrite rules

Per Cucumber's better-Gherkin guidance, "scenarios should describe the intended behaviour of the system, not the implementation" (https://cucumber.io/docs/bdd/better-gherkin/). 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.

Rule R1 - Remove UI mechanics

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

A manual script that says:

1. Type [email protected] in the email field
2. Type validPassword123 in the password field
3. Click the Submit button

…becomes one Gherkin step:

When the customer signs in with valid credentials

The five-line manual sequence collapses to a one-line When because 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

Cucumber's docs are explicit that 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 features 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. The bdd-step-library-curator skill audits and consolidates that vocabulary.

Step 3 - Emit the rewrite

Output is a markdown table side-by-side, so a reviewer can confirm semantic equivalence:

The agent assembles the surviving rows 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

Before handing the Gherkin to the automation engineer:

1. Check the project step library for matching existing steps. If the customer adds <SKU> to their cart already exists with parameter capture, the rewrite reuses it; if not, flag the new step for bdd-step-library-curator review.
2. Confirm the scenario has at most one When. Multiple Whens in one scenario indicate two scenarios were collapsed; split them.
3. Lint with the project's Gherkin linter (gherkin-lint, picklesdoc, or the IDE's built-in). Most teams pin a small ruleset (no-multiple-when, no-empty-feature, file-name-convention).
4. Diff the rewrite against the manual step's expected outcome - semantic equivalence is the bar, not literal-translation fidelity. 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.

Anti-patterns

Limitations

• Vocabulary alignment is the bottleneck, not translation. The mechanics of declarativization are rules-based; aligning with the project's existing step library requires reading that library. For large projects, run bdd-step-library-curator first to canonicalize the vocabulary.
• Some manual steps are inherently UI-mechanical. Accessibility tests that assert "the Skip to main link is the first focusable element" are not rewriteable into business language without losing the spec. Pass these through with R1 disabled and flag them in the Scenario as @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". Specificity is the load-bearing part of the assertion.
• Output is a draft. A human reviews the side-by-side before merging into the feature file; the skill does not auto-merge.

Hand-off targets

• Convert the resulting Gherkin into runnable step definitions → cucumber-testing, specflow-testing, reqnroll-testing, behave-testing.
• Audit the project's step library for vocabulary drift → bdd-step-library-curator.
• If the source is a user story, not a manual step → gherkin-from-stories.
• If the source is an AC list, not a manual step → acceptance-test-from-criteria.
• If the team is generating a test-case matrix from a story (upstream of this skill) → test-case-ideation-from-story (in the qa-process plugin).

References

• Cucumber documentation - Better Gherkin (declarative vs imperative; "scenarios should describe the intended behaviour of the system, not the implementation"): https://cucumber.io/docs/bdd/better-gherkin/
• Cucumber documentation - Gherkin reference (keyword semantics: Given / When / Then / And / But): https://cucumber.io/docs/gherkin/reference/
• ISTQB glossary - behavior-driven development: https://glossary.istqb.org/en_US/term/behavior-driven-development
• ISTQB glossary - test procedure (the imperative form this skill abstracts away from): https://glossary.istqb.org/en_US/term/test-procedure
• bdd-step-library-curator - the canonical-vocabulary skill.