Gherkin notation
Gherkin notation is a structured format for describing software behavior in natural language using three steps: Given (precondition), When (action), and Then (outcome). It is widely used as the standard notation for .feature files read by the test automation tool Cucumber.
Why Gherkin
Many teams manage test specifications separately — developers maintain them as code, while the business side keeps them as documents in Japanese or English. Every time a specification changes, both need to be updated, and discrepancies accumulate over time.
Gherkin notation addresses this problem with an "executable specification" approach. Its syntax is close to natural language that business stakeholders can read, while also being directly executable as automated tests. Because the specification and test code live in the same file, structural divergence is less likely to occur.
Basic Syntax
A typical .feature file structure looks like this:
gherkin
1Feature: User Login
2
3 Scenario: Can log in with correct credentials
4 Given the login page is displayed
5 When I enter the email address "user@example.com"
6 And I enter the password "correct-password"
7 And I click the login button
8 Then the dashboard is displayedFeature represents a unit of functionality, and Scenario corresponds to an individual test case. Conditions can be added with And / But, and parameterization is also possible using Scenario Outline with an Examples table.
Support for over 70 natural languages, including Japanese, is another notable feature — keywords can be localized directly.
Relationship with BDD
Gherkin notation emerged from BDD (Behavior-Driven Development) practices. BDD emphasizes describing "what the software should do" in a form that all stakeholders can share. Gherkin standardizes that description format, and frameworks such as Cucumber, Behave, and SpecFlow parse Gherkin files to execute tests.
Since my team started writing acceptance tests in Gherkin, reaching consensus in QA and developer review meetings — agreeing that "if this Scenario passes, we're good to release" — has become significantly faster.
Pitfalls When Adopting
It is not a silver bullet. If the granularity of step definitions (the implementation code that runs behind each Given/When/Then) is poorly designed, similar steps can proliferate rapidly, driving up maintenance costs. Additionally, writing out every fine-grained UI interaction in Gherkin tends to become verbose. Rather than converting all E2E tests to Gherkin, applying it selectively to business rule validation often yields a better cost-to-benefit ratio.
