# DamageBDD Step Reference

Canonical HTML: <https://damagebdd.com/modules/http.html>



<a id="introduction"></a>

## Introduction

This document explains the **steps** you can use when writing DamageBDD
feature files.

You do **not** need to know how DamageBDD works internally.
If you can write plain English sentences, you can write tests.

Each step describes:

-   What the step does
-   When to use it
-   An example you can copy

All steps work inside standard Gherkin files:

```gherkin
Feature: Example Feature
  Scenario: Example Scenario
    Given something
    When something happens
    Then something should be true
```


<a id="core-concepts-read-this-first"></a>

## Core Concepts (Read This First)

****Steps run in order****

-   Each step builds on the result of the previous step.
-   If one step fails, the scenario stops.

****Variables prevent repetition****

-   You can store values (IDs, tokens, responses) and reuse them later.

****Plain language wins****

-   Write what the system **should do**, not **how** it does it.


<a id="http-testing-steps"></a>

## HTTP Testing Steps

These steps let you test APIs and web services.

****Before making requests, always set a server or base URL.****


<a id="given-i-am-using-server-server"></a>

### Given I am using server "{{Server}}"

Use this to select the target system you are testing.

```gherkin
Given I am using server "https://api.example.com"
```


<a id="given-i-set-base-url-to-url"></a>

### Given I set base URL to "{{URL}}"

Same purpose as **using server**, but explicit.

```gherkin
Given I set base URL to "https://api.example.com"
```


<a id="given-i-set-header-header-to-value"></a>

### Given I set "{{Header}}" header to "{{Value}}"

Adds an HTTP header to all following requests.

```gherkin
Given I set "Authorization" header to "Bearer my-token"
```


<a id="given-i-store-cookies"></a>

### Given I store cookies

Tells DamageBDD to remember cookies between requests.
Use this for login flows.

```gherkin
Given I store cookies
```


<a id="when-i-make-a-get-request-to-path"></a>

### When I make a GET request to "{{Path}}"

Sends a GET request.

```gherkin
When I make a GET request to "/users"
```


<a id="when-i-make-a-post-request-to-path"></a>

### When I make a POST request to "{{Path}}"

Sends a POST request with a body.

```gherkin
When I make a POST request to "/login"
"""
{
  "username": "alice",
  "password": "secret"
}
"""
```


<a id="when-i-make-a-put-request-to-path"></a>

### When I make a PUT request to "{{Path}}"

Updates something.

```gherkin
When I make a PUT request to "/users/123"
"""
{
  "email": "new@example.com"
}
"""
```


<a id="when-i-make-a-patch-request-to-path"></a>

### When I make a PATCH request to "{{Path}}"

Partially updates something.


<a id="when-i-make-a-delete-request-to-path"></a>

### When I make a DELETE request to "{{Path}}"

Deletes something.

```gherkin
When I make a DELETE request to "/users/123"
```


<a id="when-i-make-a-csrf-post-request-to-path"></a>

### When I make a CSRF POST request to "{{Path}}"

Use this for systems that require CSRF protection (common in web apps).

```gherkin
When I make a CSRF POST request to "/settings"
"""
{ "dark_mode": true }
"""
```


<a id="response-validation-steps"></a>

## Response Validation Steps

These steps check what the system returned.


<a id="then-the-response-status-must-be-status"></a>

### Then the response status must be "{{Status}}"

Check the HTTP status code.

```gherkin
Then the response status must be "200"
```


<a id="then-the-response-status-must-be-one-of-statuses"></a>

### Then the response status must be one of "{{Statuses}}"

Accepts multiple valid outcomes.

```gherkin
Then the response status must be one of "200,201"
```


<a id="then-the-response-must-contain-text-contains"></a>

### Then the response must contain text "{{Contains}}"

Checks for a word or phrase.

```gherkin
Then the response must contain text "success"
```


<a id="then-the-header-header-should-be-value"></a>

### Then the "{{Header}}" header should be "{{Value}}"

Validates response headers.

```gherkin
Then the "Content-Type" header should be "application/json"
```


<a id="then-the-json-should-be"></a>

### Then the JSON should be

Checks the **entire** JSON response.

```gherkin
Then the JSON should be
"""
{ "status": "ok" }
"""
```


<a id="then-the-json-at-path-jsonpath-should-be"></a>

### Then the JSON at path "{{JsonPath}}" should be

Checks a specific field inside JSON.

```gherkin
Then the JSON at path "$.user.id" should be "123"
```


<a id="then-i-store-the-json-at-path-path-in-variable"></a>

### Then I store the JSON at path "{{Path}}" in "{{Variable}}"

Extracts data for later steps.

```gherkin
Then I store the JSON at path "$.token" in "AuthToken"
```


<a id="variables-reuse"></a>

## Variables & Reuse


<a id="i-set-the-variable-variable-to-value"></a>

### I set the variable "{{Variable}}" to "{{Value}}"

Manually define a variable.

```gherkin
Given I set the variable "UserId" to "123"
```


<a id="the-variable-variable-should-be-equal-to-json-value"></a>

### The variable "{{Variable}}" should be equal to JSON "{{Value}}"

Validate stored values.

```gherkin
Then the variable "UserId" should be equal to JSON "123"
```


<a id="authentication-steps"></a>

## Authentication Steps


<a id="then-i-set-basicauth-username-to-user-and-password-to-password"></a>

### Then I set BasicAuth username to "{{User}}" and password to "{{Password}}"

Use HTTP Basic Authentication.

```gherkin
Then I set BasicAuth username to "admin" and password to "secret"
```


<a id="then-i-use-header-oauth-with-key-key-and-secret-secret"></a>

### Then I use header OAuth with key="{{Key}}" and secret="{{Secret}}"

Adds OAuth credentials via headers.


<a id="then-i-use-query-oauth-with-key-key-and-secret-secret"></a>

### Then I use query OAuth with key="{{Key}}" and secret="{{Secret}}"

Adds OAuth credentials via URL parameters.


<a id="utility-steps"></a>

## Utility Steps

These help with timing, IDs, and dynamic data.


<a id="i-store-an-uuid-in-variable"></a>

### I store an uuid in "{{Variable}}"

Generates a unique ID.

```gherkin
Given I store an uuid in "RequestId"
```


<a id="i-store-current-time-string-in-variable-with-format-format"></a>

### I store current time string in "{{Variable}}" with format "{{Format}}"

Useful for timestamps.

```gherkin
Given I store current time string in "Now" with format "%Y-%m-%d"
```


<a id="i-wait-seconds-seconds"></a>

### I wait "{{Seconds}}" seconds

Pauses execution.

```gherkin
And I wait "2" seconds
```


<a id="writing-good-scenarios"></a>

## Writing Good Scenarios

✔ Describe **behaviour**, not implementation  
✔ One business rule per scenario  
✔ Prefer clarity over cleverness  

****Bad****

```gherkin
Then system returns 200
```

****Good****

```gherkin
Then the user sees a successful login response
```


<a id="final-advice"></a>

## Final Advice

If a stakeholder can read your feature file and say:
> “Yes, that’s exactly what the system should do”

Then you are using DamageBDD correctly.

Verification follows clarity.