Gherkin and Feature Files

Gherkin is a structured way to describe product behavior in plain language. TestVibe uses Gherkin-style feature files so test intent stays readable before it becomes generated Playwright code.

A good Gherkin feature explains what a user is trying to do, what actions they take, and what outcome proves the product worked.

info

New to the language? See the official Gherkin reference on cucumber.io for the full keyword specification.

Why Gherkin Matters In TestVibe

Gherkin gives TestVibe a clear source of truth for generation:

• Product and QA users can read and edit the expected behavior.
• AI generation has a structured description to turn into Playwright code.
• Developers can review the behavior being tested before inspecting implementation details.
• The Test Suite can organize tests by feature area, scenario, and generated status.

In a project, feature files usually live under Features/, often grouped by product area.

The Basic Shape

A Gherkin feature file usually contains a Feature, optional shared setup in Background, and one or more Scenario blocks.

Feature: Checkout

  Background:
    Given the shopper is on the store homepage

  Scenario: Complete checkout with a saved card
    Given the shopper has an item in the cart
    When the shopper completes checkout with a saved card
    Then the order confirmation should be displayed

Core Gherkin Terms

Term	What it means
Feature	The product capability or user journey being described.
Scenario	One concrete example of behavior inside the feature.
Background	Shared setup that should apply before each scenario in the feature.
Given	The starting context or precondition.
When	The action the user or system takes.
Then	The expected outcome that proves the behavior worked.
And	A continuation of the previous Given, When, or Then.
But	A contrast or exception related to the previous step.
Scenario Outline	A reusable scenario pattern that runs with different example values.
Examples	The table of values used by a scenario outline.

Feature

Use Feature to name the product behavior you want to cover.

Good feature names are user-facing and specific:

• Feature: Password reset
• Feature: Timesheet approval
• Feature: Checkout with saved payment method

Avoid feature names that are too broad, such as Feature: Website or Feature: Testing.

Scenario

Use Scenario for one concrete behavior. A scenario should usually describe a single successful path, failure path, or important variation.

Scenario: User signs in with valid credentials
  Given the user is on the sign-in page
  When the user signs in with valid credentials
  Then the dashboard should open

If a scenario starts covering several unrelated behaviors, split it into smaller scenarios.

Given, When, Then

The Given, When, Then pattern helps separate setup, action, and expected result.

Keyword	Use it for	Example
Given	Context that is already true before the main action.	Given the user is on the sign-in page
When	The important action being tested.	When the user submits valid credentials
Then	The result that should be verified.	Then the dashboard should open

The Then step is especially important for AI generation. If the expected result is vague, the generated test may only perform actions without proving the behavior worked.

Background

Use Background for setup that belongs to every scenario in the feature.

Feature: Account settings

  Background:
    Given the user is signed in
    And the account settings page is open

  Scenario: Update display name
    When the user changes the display name
    Then the new display name should be saved

Keep backgrounds short. If the setup is long or only applies to one scenario, put it inside that scenario instead.

Always Start At The Entrypoint

Every TestVibe feature must begin at the site's landing entrypoint — the page the project's configured URL opens fresh: the home page, or the login page for an app behind authentication. Put that in the Background (or the opening steps of a single-scenario feature), then navigate forward with explicit steps to whatever deeper page (Settings, a record detail, an admin screen) the scenario actually needs.

Feature: Team member roles

  Background:
    Given I am on the "Login" page
    When I sign in with "{{var:USERNAME}}" and "{{secret:PASSWORD}}"
    And I open the Settings menu
    And I click "Team members"

  Scenario: Change a member's role
    When the user changes a member's role to "Admin"
    Then the member's role should show "Admin"

Name the entrypoint by its screen state (Given I am on the home page, Given I am on the "Login" page) — never assume an already-signed-in session, an existing cart, or any other starting state that skips how the app was reached. Never hardcode a URL, domain, or localhost in a step; TestVibe already points the test at the project's configured site, so name the screen instead of the address.

Uniqueness For Created Data

A step that creates something (a sign-up email, a new project or record name) needs a value that's unique on every run — a fixed literal collides with what the previous run already created. Embed the {{unique}} token inside the value:

When the user signs up with email "casey+{{unique}}@example.com"
And the user creates a project named "Project {{unique}}"

{{unique}} expands to a fresh stamp at run time, and every occurrence within the same run resolves to the same value — so a later step can assert against or sign back in with the value an earlier step created. It takes no arguments and needs no variable definition; a value that only references existing data should stay a plain literal. Credentials and other sensitive values use {{var:NAME}} / {{secret:NAME}} tokens instead — see Add API keys and secrets.

Scenario Outlines And Examples

Use a Scenario Outline when the same behavior should be checked with different values.

Scenario Outline: Search by status
  Given the user is on the orders page
  When the user filters orders by "<status>"
  Then only "<status>" orders should be shown

  Examples:
    | status    |
    | Open      |
    | Closed    |
    | Cancelled |

Scenario outlines are useful for variations, but keep the examples meaningful. If each row needs a different workflow, separate scenarios may be easier to understand.

Good Gherkin For AI Generation

Gherkin works best in TestVibe when it gives the generator clear, testable intent.

Do:

• start every feature at the site's landing entrypoint (see above), then navigate forward
• write steps from the user's point of view
• mention visible labels, buttons, fields, and expected messages
• include the outcome that must be verified
• keep each scenario focused on one behavior
• use real test data when a specific record, date, or account matters
• put shared setup in Background only when every scenario needs it
• wrap a value that creates new data in {{unique}} so repeat runs don't collide

Avoid:

• vague steps such as When the user does the thing
• assuming a starting state (already signed in, already on a deep page) instead of reaching it step by step
• hidden expectations that are not written in a Then
• long scenarios that cover many unrelated flows
• implementation details that a user cannot observe
• hardcoding a URL, domain, or localhost — name the screen, not the address
• changing data without describing how the test should end in a repeatable state

Structure Hint

While you edit, the Gherkin editor can surface a Structure hint — an accent button next to the editor that appears when your draft could read more cleanly. Click it to open a short piece of structure advice: pulling shared setup into a Background, starting at the entrypoint, keeping each scenario self-contained, or using credential tokens instead of literal values.

When the advice comes with a concrete rewrite, an Apply button edits your draft in place so you can review it. It never saves for you — the change lands in the editor as an unsaved edit you can undo, and you still click Save when you're happy with it.

How Gherkin Becomes Playwright Code

In TestVibe, Gherkin is the readable intent. Playwright is the executable browser automation.

The typical flow is:

1. Create or edit a Gherkin feature in the Test Suite.
2. Review the feature, scenarios, and steps.
3. Start generation.
4. TestVibe uses the feature intent to generate Playwright code.
5. Run the generated test.
6. Use results and evidence to decide whether to edit the feature, regenerate, or fix the application.

Example: Before And After

Vague instruction:

Scenario: Login works
  When the user logs in
  Then it should work

Better Gherkin:

Scenario: User signs in with valid credentials
  Given the user is on the sign-in page
  When the user enters a valid email and password
  And the user clicks Sign in
  Then the dashboard should open
  And the user name should be visible in the header

The better version tells TestVibe what page to start from, what action matters, and what visible evidence proves success.

Where To Go Next

Create and organize features

• Understand the Test Suite
• Create groups and tests
• Write good test instructions

Generate from Gherkin

• Generate a new feature
• Generate Playwright code
• Review generation progress

Run and improve

• Run one test
• Inspect failed steps
• Regenerate a test