Skip to content

Steps Common Database

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

Common — Database

See Configuration#database-support for setup, database-less mode, and troubleshooting.

Introduction

The library supports end-to-end testing from REST API down to the database:

  • Liquibase scripts — seed or reset the database state before a scenario
  • SQL execution — run arbitrary SQL to prepare data
  • CSV comparison — run a SQL query and compare results against a CSV file

Automatic reset: Before every scenario, the library checks for bdd-cucumber-gherkin-lib/src/test/resources/database/reset_database.xml. If present, this Liquibase changelog is executed automatically — useful for truncating tables and re-inserting fixtures to guarantee a clean state.

Database support is active by default. Disable it with cucumberTest.databaseless=true. See Configuration#database-support.

Given — Liquibase Script Initialization

Given that the database was initialized with the liquibase file {string}

Executes a Liquibase changelog file to set up database state before the scenario. Use this in Background to apply it to all scenarios in a feature.

Feature: Order processing

  Background:
    Given that all URLs are relative to "/api/v1/orders"
    And that all file paths are relative to "features/orders"
    And that the database was initialized with the liquibase file "database/fixtures/orders_fixture.xml"

  Scenario: List all orders
    When executing an authorized GET call to ""
    Then I ensure that the status code of the response is 200
    And I ensure that the body of the response contains a field "$.length()" with the value "3"

  Scenario: Fetch a specific order
    When executing an authorized GET call to "/order-001"
    Then I ensure that the response code is 200 and the body is equal to the file "expected/order_001.json"

The Liquibase file can contain insert, delete, truncate, or any other Liquibase change type.

Examples: bdd-cucumber-gherkin-lib/src/test/resources/features/database/

Given — SQL Statement Execution

Given that the SQL statements from the SQL file {string} was executed

Executes an SQL script to prepare or modify the database. Use when you need fine-grained control over the data, or when Liquibase is not the right fit for a particular setup step.

Feature: Invoice reports

  Background:
    Given that all URLs are relative to "/api/v1/reports"
    And that the SQL statements from the SQL file "database/setup/insert_test_invoices.sql" was executed

  Scenario: Monthly summary includes all test invoices
    When executing an authorized GET call to "/invoices/monthly-summary"
    Then I ensure that the status code of the response is 200
    And I ensure that the body of the response contains a field "totalCount" with the value "5"

  Scenario: Filter invoices by status
    When executing an authorized GET call to "/invoices?status=PAID"
    Then I ensure that the status code of the response is 200

Examples: bdd-cucumber-gherkin-lib/src/test/resources/features/database/

Then — Database Data Comparison

Then I ensure that the result of the query of the file {string} is equal to the CSV file {string}

Executes an SQL SELECT query from the first file and compares the result to the CSV file. The library converts the database result to CSV internally — no manual conversion needed.

Use this to verify that an API call actually persisted the expected data in the database.

database/queries/select_active_users.sql:

SELECT id, first_name, last_name, status
FROM users
WHERE status = 'ACTIVE'
ORDER BY id

database/expected/active_users.csv:

id,first_name,last_name,status
user-001,Alice,Smith,ACTIVE
user-002,Bob,Jones,ACTIVE
Feature: User creation

  Background:
    Given that the database was initialized with the liquibase file "database/fixtures/clean_users.xml"
    And that all URLs are relative to "/api/v1/users"
    And that all file paths are relative to "features/users"

  Scenario: Created user is persisted correctly
    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 status code of the response is 201
    And I ensure that the result of the query of the file "database/queries/select_active_users.sql" is equal to the CSV file "database/expected/active_users.csv"

  Scenario: Deactivating a user updates the database
    When executing an authorized DELETE call to "/user-001"
    Then I ensure that the status code of the response is 200
    And I ensure that the result of the query of the file "database/queries/select_active_users.sql" is equal to the CSV file "database/expected/active_users_after_delete.csv"

Examples: bdd-cucumber-gherkin-lib/src/test/resources/features/database/

Clone this wiki locally