Scenarios & Tags

Every Gherkio test file describes a single test scenario. The root of the YAML document contains the top-level keys for execution metadata, tagging, and execution phases.

🏗️ Top-Level Key Reference

All keys in the Gherkio DSL are case-sensitive and must be written in lowercase.

KeyTypeRequiredDescriptionExample
scenariostringYesHuman-readable name of the test scenarioscenario: Create new user
descriptionstringNoDetailed description of what this scenario tests. Shown in HTML report headerdescription: Verify user can login with valid credentials
tagsarrayNoList of categories/labels for execution filteringtags: [smoke, active]
setuparrayNoPre-condition HTTP requests or composed files(See Setup/Teardown chapter)
stepsarrayYesPrimary sequence of API request and assertion steps(See Steps chapter)
examplesarrayNoList of variable blocks for parametrized runs(See examples section below)
teardownarrayNoPost-condition cleanup steps (guaranteed to run)(See Setup/Teardown chapter)

🏷️ Tagging & Filtering Conventions

Tags are strings that allow you to segment and filter test executions. They are extremely valuable for executing specific subsets of a test suite (e.g. running only light tests on commit, and full suites nightly).

scenario: Authenticated checkout flow
description: Verifies a logged-in user can add items to cart and complete checkout with valid payment.
tags:
  - e2e
  - checkout
  - high-priority

Filtering test runs from CLI:

# Run tests containing the 'smoke' tag
gherkio run tests/ --tag smoke

# Run tests containing BOTH 'core' AND 'user' tags (Logical AND)
gherkio run tests/ --tag core --tag user

📊 Parametrized / Data-Driven Testing (examples)

You can execute a single scenario multiple times with different datasets using the examples block. Under the hood, the test runner runs the scenario for each set of variables defined in examples.

scenario: Parametrized login validation
description: Verifies login fails with various bad inputs
examples:
  - username: "alice"
    password: "bad-password"
  - username: bob
    password: ""
steps:
  - name: Attempt login
    request:
      method: POST
      url: /api/login
      body:
        username: "{{username}}"
        password: "{{password}}"
    expect:
      status: 400