Playwright BDD Gherkin Syntax

Expert knowledge of Gherkin syntax for writing feature files in Playwright BDD, including scenarios, outlines, backgrounds, tags, and internationalization.

Overview

Gherkin is a domain-specific language for describing software behavior in plain text. Playwright BDD uses Gherkin feature files (

.feature

) that are transformed into Playwright test files via

bddgen

Feature File Structure

Basic Structure

gherkin

Feature: User Authentication
  As a user
  I want to be able to log in
  So that I can access my account

  Background:
    Given I am on the login page

  Scenario: Successful login
    When I enter valid credentials
    And I click the login button
    Then I should see the dashboard

  Scenario: Failed login
    When I enter invalid credentials
    And I click the login button
    Then I should see an error message

Feature Declaration

gherkin

Feature: Short descriptive title

  Optional description spanning
  multiple lines explaining the
  feature's purpose and context.

Keywords

Given - Preconditions

Describes the initial context or state:

gherkin

Given I am logged in as "admin"
Given the shopping cart is empty
Given the following users exist:
  | name  | email           |
  | Alice | alice@test.com  |
  | Bob   | bob@test.com    |

When - Actions

Describes the action or event:

gherkin

When I click the "Submit" button
When I fill in "email" with "test@example.com"
When I select "Express" from the shipping options
When 24 hours have passed

Then - Outcomes

Describes the expected outcome:

gherkin

Then I should see "Welcome back!"
Then the cart should contain 3 items
Then I should be redirected to the dashboard
Then an email should be sent to "test@example.com"

And / But - Continuation

Continues the previous Given/When/Then:

gherkin

Given I am logged in
And I have items in my cart
But I have not entered a shipping address

When I click checkout
And I enter my payment details

Then I should see the confirmation page
And I should receive an order email
But I should not be charged twice

Scenario Types

Basic Scenario

gherkin

Scenario: Add item to cart
  Given I am on the product page
  When I click "Add to Cart"
  Then the cart count should be 1

Scenario Outline (Data-Driven)

Run the same scenario with different data:

gherkin

Scenario Outline: Login with different roles
  Given I am on the login page
  When I login as "<role>"
  Then I should see the "<dashboard>" dashboard

  Examples:
    | role    | dashboard |
    | admin   | Admin     |
    | user    | User      |
    | manager | Manager   |

Multiple example tables:

gherkin

Scenario Outline: Product pricing
  Given I am viewing product "<product>"
  Then the price should be "<price>"
  And the discount should be "<discount>"

  Examples: Regular Products
    | product | price  | discount |
    | Laptop  | $999   | 0%       |
    | Mouse   | $29    | 0%       |

  Examples: Sale Products
    | product    | price  | discount |
    | Keyboard   | $79    | 20%      |
    | Headphones | $149   | 15%      |

Background (Shared Setup)

Runs before each scenario in the feature:

gherkin

Feature: Shopping Cart

  Background:
    Given I am logged in
    And I have an empty cart

  Scenario: Add single item
    When I add "Product A" to cart
    Then the cart should have 1 item

  Scenario: Add multiple items
    When I add "Product A" to cart
    And I add "Product B" to cart
    Then the cart should have 2 items

Rule (Grouping Related Scenarios)

Group scenarios under business rules:

gherkin

Feature: Discount System

  Rule: Bulk discounts apply to orders over 10 items

    Scenario: Order with 10 items gets no discount
      Given I have 10 items in my cart
      Then I should see no discount applied

    Scenario: Order with 11 items gets bulk discount
      Given I have 11 items in my cart
      Then I should see a 10% discount applied

  Rule: VIP members get additional discounts

    Scenario: VIP member gets member discount
      Given I am a VIP member
      When I view my cart
      Then I should see a 5% member discount

Data Tables

Simple Lists

gherkin

Scenario: Add multiple items
  When I add the following items:
    | Milk   |
    | Bread  |
    | Butter |

Key-Value Tables

gherkin

Scenario: Fill registration form
  When I fill in the form with:
    | First Name | John           |
    | Last Name  | Doe            |
    | Email      | john@test.com  |
    | Password   | secret123      |

Tables with Headers

gherkin

Scenario: Create multiple users
  Given the following users exist:
    | username | email           | role  |
    | alice    | alice@test.com  | admin |
    | bob      | bob@test.com    | user  |
    | carol    | carol@test.com  | user  |

Complex Tables

gherkin

Scenario: Order with multiple products
  When I create an order with:
    | product   | quantity | price | discount |
    | Laptop    | 1        | 999   | 0%       |
    | Mouse     | 2        | 29    | 10%      |
    | Keyboard  | 1        | 79    | 5%       |
  Then the order total should be $1123.55

Doc Strings

Plain Text

gherkin

Scenario: Submit feedback
  When I enter the following feedback:
    """
    Great product! Would recommend.
    Fast shipping and excellent quality.
    """
  And I click submit
  Then I should see "Thank you for your feedback"

JSON Content

gherkin

Scenario: Create product via API
  When I send a POST request with:
    """json
    {
      "name": "New Product",
      "price": 49.99,
      "category": "electronics",
      "tags": ["new", "featured"]
    }
    """
  Then the response status should be 201

Code Blocks

gherkin

Scenario: Execute script
  When I run the following script:
    """javascript
    const result = await page.evaluate(() => {
      return document.title;
    });
    console.log(result);
    """

Internationalization (i18n)

Language Header

gherkin

# language: de
Funktionalität: Benutzeranmeldung

  Grundlage:
    Angenommen ich bin auf der Anmeldeseite

  Szenario: Erfolgreiche Anmeldung
    Wenn ich gültige Anmeldedaten eingebe
    Dann sollte ich das Dashboard sehen

Supported Languages

Common languages and their keywords:

German (de):

gherkin

# language: de
Funktionalität: Feature title
  Szenario: Scenario title
    Angenommen: Given
    Wenn: When
    Dann: Then
    Und: And
    Aber: But

French (fr):

gherkin

# language: fr
Fonctionnalité: Feature title
  Scénario: Scenario title
    Soit: Given
    Quand: When
    Alors: Then
    Et: And
    Mais: But

Spanish (es):

gherkin

# language: es
Característica: Feature title
  Escenario: Scenario title
    Dado: Given
    Cuando: When
    Entonces: Then
    Y: And
    Pero: But

Comments

gherkin

Feature: Product Catalog
  # This feature covers the product listing pages

  # TODO: Add search functionality tests
  Scenario: View all products
    Given I am on the catalog page
    # Check that products load
    Then I should see at least 10 products

Best Practices

Write Declarative Steps

Good (declarative):

gherkin

Given I am logged in as an admin
When I create a new product
Then the product should be visible in the catalog

Bad (imperative):

gherkin

Given I navigate to "/login"
And I type "admin@test.com" in the email field
And I type "password123" in the password field
And I click the login button
And I wait for the dashboard to load
When I click the "Products" menu item
And I click "Add New"
...

Use Meaningful Scenario Names

Good:

gherkin

Scenario: Logged-in user can add items to wishlist
Scenario: Guest users are prompted to register before checkout
Scenario: Expired promo codes show clear error message

Bad:

gherkin

Scenario: Test 1
Scenario: Check wishlist
Scenario: Error test

Keep Scenarios Independent

Each scenario should work in isolation:

gherkin

# Good - each scenario sets up its own state
Scenario: Edit existing product
  Given a product "Test Product" exists
  When I edit the product name to "Updated Product"
  Then I should see "Updated Product" in the list

# Bad - depends on previous scenario
Scenario: Edit the product
  # Assumes product from previous scenario exists
  When I edit the product name
  Then it should be updated

Use Background Wisely

Only put truly common setup in Background:

gherkin

# Good - common setup
Background:
  Given I am logged in

# Bad - too specific
Background:
  Given I am logged in
  And I have created a product "Widget"
  And the product has 5 reviews
  And the product is on sale

Organize with Tags

gherkin

@e2e @checkout
Feature: Checkout Process

  @smoke @critical
  Scenario: Complete checkout with credit card
    ...

  @regression
  Scenario: Checkout with PayPal
    ...

  @slow @integration
  Scenario: Checkout with inventory sync
    ...

Avoid Too Many Steps

Keep scenarios focused (ideally 3-7 steps):

Good:

gherkin

Scenario: Add item to cart
  Given I am viewing a product
  When I click "Add to Cart"
  Then the cart should show 1 item

Bad (too many steps):

gherkin

Scenario: Complete purchase
  Given I am logged in
  And I am on the home page
  And I search for "laptop"
  And I click on the first result
  And I select color "silver"
  And I select memory "16GB"
  And I click add to cart
  And I view my cart
  And I click checkout
  And I enter my address
  And I select shipping method
  And I enter credit card details
  And I confirm the order
  Then I should see order confirmation
  # Too long - break into multiple scenarios

Common Patterns

Setup and Verification Pattern

gherkin

Scenario: Delete a product
  Given a product "Test Product" exists     # Setup
  When I delete "Test Product"               # Action
  Then "Test Product" should not be visible  # Verification

State Transition Pattern

gherkin

Scenario: Order lifecycle
  Given an order in "pending" status
  When I process the order
  Then the order status should be "processing"

  When I ship the order
  Then the order status should be "shipped"

  When the order is delivered
  Then the order status should be "completed"

Error Handling Pattern

gherkin

@error-handling
Scenario: Invalid form submission
  Given I am on the registration page
  When I submit the form with:
    | email    | invalid-email |
    | password | 123           |
  Then I should see the following errors:
    | field    | message                    |
    | email    | Please enter a valid email |
    | password | Password too short         |

File Organization

features/
├── authentication/
│   ├── login.feature
│   ├── logout.feature
│   └── password-reset.feature
├── products/
│   ├── catalog.feature
│   ├── search.feature
│   └── product-details.feature
├── checkout/
│   ├── cart.feature
│   ├── payment.feature
│   └── shipping.feature
└── admin/
    ├── user-management.feature
    └── product-management.feature

When to Use This Skill

Writing new feature files
Converting requirements to Gherkin scenarios
Using Scenario Outline for data-driven tests
Organizing tests with tags
Setting up shared Background steps
Working with internationalized features
Reviewing and improving feature file quality
Training team members on BDD syntax

playwright-bdd-gherkin-syntax

NPX Install

Tags

SKILL.md Content

Playwright BDD Gherkin Syntax

Overview

Feature File Structure

Basic Structure

Feature Declaration

Keywords

Given - Preconditions

When - Actions

Then - Outcomes

And / But - Continuation

Scenario Types

Basic Scenario

Scenario Outline (Data-Driven)

Background (Shared Setup)

Rule (Grouping Related Scenarios)

Tags

Basic Tags

Special Playwright BDD Tags

Tag Expressions

Tag Inheritance

Data Tables

Simple Lists

Key-Value Tables

Tables with Headers

Complex Tables

Doc Strings

Plain Text

JSON Content

Code Blocks

Internationalization (i18n)

Language Header

Supported Languages

Comments

Best Practices

Write Declarative Steps

Use Meaningful Scenario Names

Keep Scenarios Independent

Use Background Wisely

Organize with Tags

Avoid Too Many Steps

Common Patterns

Setup and Verification Pattern

State Transition Pattern

Error Handling Pattern

File Organization

When to Use This Skill