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.

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')
 

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

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 \
    'https://run.damagebdd.com/execute_feature'

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

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:

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 \
    https://run.damagebdd.com/reports/

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 \
    https://run.damagebdd.com/reports/

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

REPORT_HASH="REPORT_HASH"
curl \
    -H "Authorization: Bearer "$AUTH_TOKEN \
    https://run.damagebdd.com/reports/$REPORT_HASH/

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

DAMAGE_PID="PID"
REPORT_HASH="REPORT_HASH"
curl \
    -H "Authorization: Bearer "$AUTH_TOKEN \
    https://run.damagebdd.com/reports/$REPORT_HASH/$DAMAGE_PID.color.txt

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:

DAMAGE_TUNNEL_START=$(curl \
    -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:

DAMAGE_SSH_SERVER_PORT=8989
LOCAL_SERVER_PORT=8080

ssh -x run.damagebdd.com \
    -p 8989 \
    -L $DAMAGE_TUNNEL_START:localhost:$LOCAL_SERVER_PORT

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.

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