# 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. ## 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 connected repository, 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. ```gherkin 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. ```gherkin 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. ```gherkin 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. ## Scenario Outlines And Examples Use a `Scenario Outline` when the same behavior should be checked with different values. ```gherkin Scenario Outline: Search by status Given the user is on the orders page When the user filters orders by "" Then only "" 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: * 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 Avoid: * vague steps such as `When the user does the thing` * hidden expectations that are not written in a `Then` * long scenarios that cover many unrelated flows * implementation details that a user cannot observe * changing data without describing how the test should end in a repeatable state ## 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: ```gherkin Scenario: Login works When the user logs in Then it should work ``` Better Gherkin: ```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
Generate from Gherkin
Run and improve
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.testvibe.com/create-tests/gherkin-and-feature-files.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.