Skip to content

Steps When Polling

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

When — Polling

Introduction

Polling steps call an endpoint repeatedly until the expected HTTP status code (and optionally response body) is received, or until the configured retry limit is exhausted.

Use polling instead of Then I wait for {int} ms (Then — Timing) when the endpoint gives an observable signal that processing is complete — poll until the signal appears rather than sleeping for a fixed time.

The polling configuration resets before each scenario. The URL and body must be set with Given steps before the polling When step runs.

Configure Polling

Single-line (preferred):

Given that a request polls every {int} seconds for {int} times

Two separate steps (useful when splitting config between Background and Scenario):

Given that a requests polls every {int} seconds
And that a requests polls for {int} times

Example using both:

Feature: Async jobs

  Background:
    Given that all URLs are relative to "/api/v1/jobs"
    And that a requests polls every 2 seconds

  Scenario: Short job completes in under 10 seconds
    And that a requests polls for 5 times
    And that the API path is "/job-123"
    When executing an authorized GET poll request until the response code is 200

  Scenario: Long job allows more retries
    And that a requests polls for 15 times
    And that the API path is "/job-456"
    When executing an authorized GET poll request until the response code is 200

Poll Until HTTP Code Matches

Polls until the response status code equals the expected value. The response body is ignored.

Authorized:

When executing an authorized {httpMethod} poll request until the response code is {int}

Unauthorized:

When executing a {httpMethod} poll request until the response code is {int}
Scenario: Wait for a resource to become available
  Given that a request polls every 1 seconds for 10 times
  And that the API path is "/api/v1/resources/abc"
  When executing an authorized GET poll request until the response code is 200

Scenario: Wait for a background deletion to complete
  Given that a request polls every 2 seconds for 5 times
  And that the API path is "/api/v1/jobs/cleanup-123"
  When executing a GET poll request until the response code is 204

Poll Until HTTP Code and Body Match (JSON file)

Polls until both the response code and the response body match. The expected body is loaded from a file.

Authorized:

When executing an authorized {httpMethod} poll request until the response code is {int} and the body is equal to file {string}

Unauthorized:

When executing a {httpMethod} poll request until the response code is {int} and the body is equal to file {string}
Feature: Job processing

  Background:
    Given that all file paths are relative to "features/jobs"
    And that a request polls every 1 seconds for 10 times

  Scenario: Job completes with expected status
    Given that the API path is "/api/v1/jobs/job-123"
    When executing an authorized GET poll request until the response code is 200 and the body is equal to file "expected/job_complete.json"

  Scenario: Public job reaches completed state
    Given that the API path is "/api/v1/public/jobs/job-456"
    When executing a GET poll request until the response code is 200 and the body is equal to file "expected/job_complete.json"

features/jobs/expected/job_complete.json:

{
  "status": "COMPLETED",
  "result": "${json-unit.matches:isValidUUID}"
}

See JSON-Unit for available matchers in the expected file.

Poll Until HTTP Code and Body Match (inline JSON)

Polls until both the response code and the response body match an inline JSON doc-string.

Authorized:

When executing an authorized {httpMethod} poll request until the response code is {int} and the body is equal to
  """
  { "status": "DONE" }
  """

Unauthorized:

When executing a {httpMethod} poll request until the response code is {int} and the body is equal to
  """
  { "status": "DONE" }
  """
Scenario: Wait for job to report SUCCESSFUL
  Given that a request polls every 1 seconds for 5 times
  And that the API path is "/api/v1/jobs/job-123"
  When executing an authorized GET poll request until the response code is 200 and the body is equal to
    """
    {
      "status":  "SUCCESSFUL",
      "jobId":   "job-123"
    }
    """

Scenario: Public endpoint — wait for READY state
  Given that a request polls every 2 seconds for 3 times
  And that the API path is "/api/v1/public/status"
  When executing a GET poll request until the response code is 200 and the body is equal to
    """
    { "ready": true }
    """

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

Clone this wiki locally