How Gherkin Helps Teams Write Better Acceptance Tests

Gherkin is a structured language for describing behavior through examples. Cucumber is a tool that can execute those examples by matching their steps to code. A feature file is readable specification; it becomes an automated check only when step definitions perform actions and assertions against the system.

Write the example together

Bring product, engineering and QA together before implementation. Pick a business rule, a normal example, an edge case and an unanswered question. Write outcomes people can observe rather than a long script of interface clicks. Collaboration is the point of behavior-driven development; adding a .feature file alone does not create it.

For example, consider a fictional invitation tool. The rule is that invited members must fit the workspace’s remaining seat capacity. This is an illustrative rule, not a description of a real platform.

Scenario and Scenario Outline

The official Gherkin reference, reviewed September 8, 2026, defines the syntax. Given establishes context, When describes an action, and Then checks an outcome. And and But make repeated step types easier to read.

Feature: Workspace invitations
  Scenario: Invite within capacity
    Given a workspace has 3 available seats
    When the owner invites 2 people
    Then the invitation result is "accepted"

  Scenario Outline: Check invitation capacity
    Given a workspace has <available> available seats
    When the owner invites <requested> people
    Then the invitation result is "<result>"

    Examples:
      | available | requested | result   |
      | 3         | 3         | accepted |
      | 3         | 4         | rejected |
      | 0         | 1         | rejected |

A Scenario is one example. A Scenario Outline substitutes each data row into its steps, producing one example per row. In this file that means four scenarios in total.

Feature groups related behavior. An optional Rule groups scenarios illustrating one business rule. A Background holds shared setup steps that run before each scenario in its scope; use at most one per Feature or Rule. Keep it short so readers can understand each example without reconstructing a hidden setup story.

Connect the words to executable checks

Cucumber’s step-definition documentation explains how expressions match step text and pass values to code. Here is a complete small JavaScript example for a separate learning project with @cucumber/cucumber installed. Save the feature above as features/invitations.feature and this file as features/step_definitions/invitations.cjs:

const { Given, When, Then } = require('@cucumber/cucumber');
const assert = require('node:assert/strict');

function invitationResult(available, requested) {
  return requested <= available ? 'accepted' : 'rejected';
}

Given('a workspace has {int} available seats', function (available) {
  this.available = available;
});
When('the owner invites {int} people', function (requested) {
  this.result = invitationResult(this.available, requested);
});
Then('the invitation result is {string}', function (expected) {
  assert.equal(this.result, expected);
});

Run npx cucumber-js in that learning project. The small function stands in for the application’s decision boundary. In a real project, call the actual domain function, API or interface instead of duplicating its logic in the test. Add input validation and authorization tests where they belong; this example does not cover those concerns.

Change the last expected result to accepted and rerun: the assertion should fail. Restore it after checking. This deliberate failure demonstrates that the assertion checks behavior.

Know what a passing scenario proves

Changing descriptive prose or a scenario title does not automatically fail a test. Changing a step may make it undefined, match different code or still pass. Changing an expected result should fail only when the implementation disagrees and the assertion actually checks it.

Passing examples establish only the cases exercised through the chosen test boundary. They do not prove that every requirement, permission, browser state or performance target is correct. Keep lower-level tests and exploratory testing where they provide better feedback.

Keep scenarios useful as the product changes

Review feature files with the same care as requirements. Use consistent domain terms, avoid broad reusable steps that hide intent, and keep each scenario focused on one rule or behavior. Update the example and implementation together when the business rule changes; do not weaken assertions merely to restore a green build.

Gherkin fits when non-technical reviewers actively use the examples and the rules benefit from shared discussion. It adds maintenance cost when only engineers read it or every step mirrors low-level code. In that case, plain examples in a ticket plus focused automated tests may be simpler.

For a software delivery plan, decide which acceptance examples need automation and who maintains them. Hapy’s MVP development work can include that agreement before build, so the first release has clear acceptance criteria and honest limits.