Behaviour Driven Development At Planetary Scale.

DamageBDD User Manual: Get Started with Behavior Testing in Minutes!

Get Started with Behavior Testing in Minutes!

Welcome to DamageBDD, the powerful and user-friendly behavior testing platform designed to help you automate your application testing process. In this quick start guide, we'll walk you through setting up an account, writing a simple test using your editor, and running it using cURL.

Let's dive in! *

[*] please read usage terms & conditions here

Create an Account

To get started with DamageBDD, you need to create an account.

You can do this by signing up using the web ui at https://run.damagebdd.com or

using the `curl` command and sending a POST request to our account creation endpoin:

curl \
    'https://run.damagebdd.com/accounts/create' \
    -H 'Content-Type: application/x-yaml' \
    -d 'email: john.doe@example.com'

Check your email for a confirmation, then set up a password at the DamageBDD website.

Get a Bearer Token

Next, you need to get a bearer token by authenticating with DamageBDD:

curl -X POST \
    'https://run.damagebdd.com/auth/' \
    --json '{
        "grant_type": "password",
        "username": "your damagebdd username/email",
        "password": "your damagebdd password",
        "scope": "basic"

Store the token securely. You will use it in your future requests to DamageBDD.

Heres is an example of fetching and storing an auth token using pass and jq:

export AUTH_TOKEN=$( \
    curl -sN -X POST "https://run.damagebdd.com/auth/" \
        -d "grant_type=password&username="\
        $(pass damagebdd/username)"&password="\
        $(pass damagebdd/password)"&scope=basic" \
        | jq -r '.access_token')

Quick introduction to Gherkin

Before we move on to writing a running test, here is a quick introduction to the simple Gherkin syntax that DamageBDD uses.

Introduction to Gherkin

DamageBDD contains a suite of predefined steps that you can use to create rich test cases. Configurable step aliases are a planned feature that will enable users to configure the step definition to suite the organization's vocabulary.

Available Steps

Running a Test

Now that you have an account and a bearer token, let's write and run a simple test using Gherkin syntax:

Feature: Http test feature
  Scenario: Test post json
    Given I am using server "https://run.damagebdd.com"
    And I set "Content-Type" header to "application/json"
    When I make a POST request to "/tests/"
        "echo": "test"
    Then the response status must be "201"
    Then the json at path "$.echo" must be "test"

Save this test in a file called echotest.feature, and then run it using `curl`:

curl -N \
    --data-binary @features/echotest.feature \
    -H "Authorization: Bearer "$AUTH_TOKEN \

where $AUTH_TOKEN is the bearer token can be retrieved in the previous step.

Authorized Domains

Domain authorization is implemented in the DamageBDD behavior testing and load testing platform to ensure that only authorized domains can run tests through the network. This helps maintain the security and integrity of the network by restricting access to trusted domains.

To interact with the domain authorization feature, users can use the following API endpoints:

List Domain Tokens

curl -X GET \
    -H "Authorization: Bearer "$AUTH_TOKEN \

Generate Token for Domain

curl -X PUT \
    -H "Authorization: Bearer "$AUTH_TOKEN \
    https://run.damagebdd.com/accounts/domains --json '{"domain": "example.com"}'

By utilizing these endpoints, users can manage and authorize domains for testing purposes effectively.

Available Steps

Step reference can be found here.

To get the most current list of step implementations:

curl https://run.damagebdd.com/steps.yaml


To fetch the report for previous runs find the report hash of the run.

For example to fetch all reports since the last one day:

curl -X POST \
    --json "{"since": "1day"}" \
    -H "Authorization: Bearer "$AUTH_TOKEN \

Another example to query run records by result status of "success" or "failure". This will return the run records for previous runs filtered by feature exit status.

curl -X POST \
    --json "{"since": "3hours", "status": "success"}" \
    -H "Authorization: Bearer "$AUTH_TOKEN \

To get the list of available reports for a specific run use the report hash

curl \
    -H "Authorization: Bearer "$AUTH_TOKEN \

To get a specific report in a report hash, get <DAMAGE_PID> from the above list output

curl \
    -H "Authorization: Bearer "$AUTH_TOKEN \


Create a repeating scheduled run

curl -v -N \
    --data-binary @features/damage_http.feature \
    -H "Authorization: Bearer "$AUTH_TOKEN \

List schedules

To list all the scheduled jobs for a user.

curl -v -N \
    -H "Authorization: Bearer "$AUTH_TOKEN \

Delete schedules

To delete a scheduled job, use the id from the listing in the following request

curl -v -N \
    -H "Authorization: Bearer "$AUTH_TOKEN \

Localhost Testing Tunnel

Experimental Feature

To run tests on localhost using DamageBDD, you can utilize the ssh reverse tunneling feature. Please note that this feature is currently in the experimental phase.

To set up the tunnel, follow these steps:

  1. Make a POST request to https://run.damagebdd.com/tunnels/ with the following parameters:

    -X POST -D "{
  "local_port": 8080,
  "pub_key": "$SSH_PUBLIC_KEY"
    -H "Authorization: Bearer "$AUTH_TOKEN \
    https://run.damagebdd.com/tunnels/)|jq -r '.tunnel_start_port')
  1. Once the request is successful, use the ssh client to establish the tunnel by running the following command:


ssh -x run.damagebdd.com \
    -p 8989 \

You now have a tunnel set up from the damagebdd server to your server running on localhost. Any tests you submit that refer to localhost will be executed against the localhost server through this tunnel.

Please note that this feature is still being refined, and it may undergo changes and improvements. If you encounter any issues or have any feedback, please let us know.


Swagger UI for the REST API can be found here.

WebInterface (experimental)

Here is the link to the experimental web interface, using curl is the current recommended method.