Skip to content

Steps Given

Jump to bottom
Jörg Flade edited this page Jun 24, 2026 · 4 revisions

Given — Request Setup

Set Base Path for URLs

Given that all URLs are relative to {string}

Sets an internal base URL path for all When steps in the Scenario or Feature. Avoids repeating a common prefix like /api/v1/users before every endpoint.

Supports ${placeholder} syntax — values are resolved from ScenarioContext:

Feature: Users API

  Background:
    Given that all URLs are relative to "/api/v1/users"

  Scenario: Fetch all users
    When executing an authorized GET call to ""
    Then I ensure that the status code of the response is 200

  Scenario: Fetch a specific user
    When executing an authorized GET call to "/123"
    Then I ensure that the status code of the response is 200

  Scenario: Delete a user
    When executing an authorized DELETE call to "/123"
    Then I ensure that the status code of the response is 204

With a context placeholder (e.g. set from a previous step or application.yml):

Background:
  Given that all URLs are relative to "/api/v1/${TENANT_ID}/resources"

Set a URI Path for Later Execution

Given that the API path is {string}

Stores a URI path so it can be used by a subsequent When step. Required when the URI needs manipulation before execution — for example, when using the dynamic URI Elements table or when setting the body and URI separately.

Scenario: Fetch a resource using a pre-stored path
  Given that the API path is "/api/v1/users/123"
  When executing an authorized GET call with previously given URI
  Then I ensure that the status code of the response is 200

Scenario: Use a path with a template placeholder
  Given that the API path is "/api/v1/orders/{orderId}/items/{itemId}"
  When executing an authorized GET call with previously given API path and these dynamic 'URI Elements' replaced with the 'URI Values'
    | URI Elements | URI Values |
    | orderId      | order-abc  |
    | itemId       | item-xyz   |
  Then I ensure that the status code of the response is 200

Set a Body from JSON File for Later Execution

Given that the file {string} is used as the body

Loads a JSON file as the request body for a subsequent When step. Required when you need to combine a pre-set body with dynamic URI element substitution, or when you simply prefer to keep large request bodies in files.

The file path respects the base file path set by Set Base Path for Files.

Feature: Orders API

  Background:
    Given that all URLs are relative to "/api/v1/orders"
    And that all file paths are relative to "features/orders"

  Scenario: Create an order from a request file
    Given that the file "request/create_order.json" is used as the body
    When executing an authorized POST call with previously given URI and body
    Then I ensure that the status code of the response is 201
    And I ensure that the body of the response is equal to the file "expected/created_order.json"

  Scenario: Update an order item (file body + dynamic URI)
    Given that the API path is "/api/v1/orders/{orderId}/items/{itemId}"
    And that the file "request/update_item.json" is used as the body
    When executing an authorized PUT call with previously given API path, body and these dynamic 'URI Elements' replaced with the 'URI Values'
      | URI Elements | URI Values |
      | orderId      | order-123  |
      | itemId       | item-456   |
    Then I ensure that the status code of the response is 200

Set a Body Directly for Later Execution

Given that the body of the request is
  """
  {
    "key": "value"
  }
  """

Sets the request body inline using a Gherkin doc-string. Use this for short, scenario-specific payloads. For reusable payloads, prefer a file.

Scenario: Create a user with inline body
  Given that the body of the request is
    """
    {
      "firstName": "John",
      "lastName":  "Doe",
      "email":     "john.doe@example.com"
    }
    """
  When executing an authorized POST call to "/api/v1/users" with previously given body
  Then I ensure that the status code of the response is 201

Scenario: Update with inline body then verify
  Given that the body of the request is
    """
    { "status": "INACTIVE" }
    """
  When executing an authorized PATCH call to "/api/v1/users/123" with previously given body
  Then I ensure that the response code is 200 and the body is equal to
    """
    {
      "id":     "123",
      "status": "INACTIVE"
    }
    """

Body Manipulation

Given I set the value of the previously given body property {string} to {string}

Replaces a field in the request body that was set by a previous Given step (file or inline). Useful when a single base body is reused across multiple scenarios with small differences.

The property argument supports:

  • Simple field name: "name"
  • Nested path (dot notation): "address.city" or "$.address.city"
  • Array element: "items[0].id" or "$.items[0].id" 
Feature: Order items

  Background:
    Given that all file paths are relative to "features/orders"
    And that the file "request/create_order.json" is used as the body

  Scenario: Create an express order
    Given I set the value of the previously given body property "deliveryType" to "EXPRESS"
    When executing an authorized POST call to "/api/v1/orders" with previously given body
    Then I ensure that the status code of the response is 201

  Scenario: Create a standard order with a modified item
    Given I set the value of the previously given body property "items[0].quantity" to "5"
    And I set the value of the previously given body property "items[0].sku" to "SKU-999"
    When executing an authorized POST call to "/api/v1/orders" with previously given body
    Then I ensure that the status code of the response is 201

bdd_lib_numbers

Generates a repeating numeric string of the specified digit length. Uses the pattern 1234567890 repeated until the required length is reached.

Given I set the value of the previously given body property "accountNumber" to "10 bdd_lib_numbers"
# sets accountNumber to: 1234567890

Given I set the value of the previously given body property "pin" to "4 bdd_lib_numbers"
# sets pin to: 1234

bdd_lib_uuid

Generates a random UUID and sets it as the field value.

Given I set the value of the previously given body property "correlationId" to "bdd_lib_uuid"

Set Base Path for Files

Given that all file paths are relative to {string}

Sets a base directory for all file references in subsequent steps:

  • Request body files (Given that the file … is used as the body)
  • Response comparison files (Then I ensure that the body of the response is equal to the file …)
  • Database query files (.sql)
  • Database CSV result files (.csv)

Set this in Background so every scenario in the feature shares the same base path. If it ever changes, you update it in one place.

Feature: Users API

  Background:
    Given that all file paths are relative to "features/users"
    And that all URLs are relative to "/api/v1/users"

  Scenario: Create a user
    Given that the file "request/create_user.json" is used as the body
    When executing an authorized POST call to "" with previously given body
    Then I ensure that the body of the response is equal to the file "expected/created_user.json"

  Scenario: Fetch a user
    When executing an authorized GET call to "/123"
    Then I ensure that the body of the response is equal to the file "expected/user_123.json"

To reference a file from the classpath root regardless of the base path, prefix with absolutePath::

Then I ensure that the body of the response is equal to the file "absolutePath:shared/expected/common_error.json"

Header Manipulation

Simple Header Manipulation

Given I set the header {string} to {string}

Adds or overrides a single request header. Both the header name and value support ScenarioContext lookup — if the value string matches a key in the context, the stored value is used instead.

Scenario: Call with a custom tenant header
  Given I set the header "X-Tenant-ID" to "tenant-acme"
  When executing an authorized GET call to "/api/v1/resources"
  Then I ensure that the status code of the response is 200

Scenario: Use a header value from context
  Given that the context contains the key "MY_TENANT" with the value "tenant-acme"
  And I set the header "X-Tenant-ID" to "MY_TENANT"
  When executing an authorized GET call to "/api/v1/resources"
  Then I ensure that the status code of the response is 200

Prefix for Header Manipulation

Given I set the header {string} to {string} prefixed by {string}

Sets a header to <prefix><value>. Both the prefix and the value can be context keys.

Scenario: Set a prefixed header
  Given I set the header "X-Custom-Header" to "ABC_DEF" prefixed by "PRE_"
  # sends: X-Custom-Header: PRE_ABC_DEF
  When executing an authorized GET call to "/api/v1/resources"
  Then I ensure that the status code of the response is 200

See examples at bdd-cucumber-gherkin-lib/src/test/resources/features/header/

Clone this wiki locally