Get Started with Behavior Testing in Minutes!

Step 1: 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 by using the curl command to send a POST request to our account creation endpoint:

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

After sending the request, check your email for a confirmation, then set up a password at the DamageBDD website.

Step 2: Get a Bearer Token

Next, you need to get a bearer token by authenticating with DamageBDD. You can do this by sending a POST request with your credentials to the authentication endpoint.

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 returned token securely. You will need this token in your future requests to DamageBDD.

Here's an example of how you can fetch and store the authentication token securely 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')

This will store your bearer token in the AUTH_TOKEN environment variable.

Quick Introduction to Gherkin

Before we dive into writing tests, here's a quick introduction to the simple Gherkin syntax used by DamageBDD. DamageBDD comes with a suite of predefined steps that you can use to create rich test cases.

Configurable step aliases are a planned feature to enable users to configure step definitions that align with their organization's vocabulary.

Available Steps

You can use these predefined steps in your tests to streamline the creation of scenarios.

Step 3: Write and Run a Test

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

The test will perform an HTTP POST request and check the response using predefined steps.

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 the test above in a file called echotest.feature.

To execute the test, use the following curl command:

curl -N \
    --data-binary @features/echotest.feature \
    -H "Authorization: Bearer $AUTH_TOKEN" \
    'https://run.damagebdd.com/execute_feature'

Here, $AUTH_TOKEN should be replaced with the bearer token you obtained in Step 2.

Step 4: Domain Authorization

Domain authorization ensures that only authorized domains can run tests through the DamageBDD platform. This is important to maintain security and integrity by restricting access to trusted domains.

To manage domain authorization, you can use the following API endpoints:

1. List Domain Tokens

Use this endpoint to get a list of authorized domain tokens.

curl -X GET \
    -H "Authorization: Bearer $AUTH_TOKEN" \
    https://run.damagebdd.com/accounts/domains

2. Generate Token for Domain

Use this endpoint to generate a new token for a specific domain.

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

Replace example.com with the domain you want to authorize.

Available Steps

For a complete list of available step implementations, you can use the following command:

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

Step 5: Reporting

To fetch reports for previous test runs, you'll need the report hash of the run. Use the following endpoints to query reports based on time or status:

1. Fetch Reports Since Last 1 Day

This example fetches all reports from the last 1 day.

curl -X POST \
    --json '{"since": "1day"}' \
    -H "Authorization: Bearer $AUTH_TOKEN" \
    https://run.damagebdd.com/reports/

2. Fetch Reports by Status (Success or Failure)

Query run records by the result status (e.g., "success" or "failure") to filter runs by their exit status.

curl -X POST \
    --json '{"since": "3hours", "status": "success"}' \
    -H "Authorization: Bearer $AUTH_TOKEN" \
    https://run.damagebdd.com/reports/

3. Get Available Reports for a Specific Run

To get a 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/

4. Get a Specific Report from the Report Hash

To get a specific report, you'll need to fetch the DAMAGE_PID from the previous list output and then fetch the report.

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

Step 6: Scheduling

You can create, list, and delete scheduled runs using the DamageBDD API. Here’s how you can manage scheduled jobs:

1. Create a Repeating Scheduled Run

To schedule a repeating run (for example, a daily job), use the following `curl` command:

curl -N \
    --data-binary @features/damage_http.feature \
    -H "Authorization: Bearer $AUTH_TOKEN" \
    'https://run.damagebdd.com/schedule/daily/every/10/sec'

2. List All Schedules

To list all scheduled jobs for your user account, use the following `curl` command:

curl -N \
    -H "Authorization: Bearer $AUTH_TOKEN" \
    'https://run.damagebdd.com/schedule/'

3. Delete a Scheduled Job

If you want to delete a scheduled job, use the schedule ID from the list and delete it with the following `curl` command:

curl -v -N \
    -X DELETE \
    -H "Authorization: Bearer $AUTH_TOKEN" \
    'https://run.damagebdd.com/schedule/${SCHEDULE_ID}/'

Step 7: Localhost Testing Tunnel (Experimental Feature)

To run tests on your localhost using DamageBDD, you can utilize the SSH reverse tunneling feature. Please note that this feature is experimental and may undergo changes.

1. Setup the Tunnel

To set up the tunnel, make a POST request to the following endpoint with your local port and SSH public key:

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'

2. Establish the SSH Tunnel

Once the request is successful, use the SSH client to establish the tunnel:

DAMAGE_SSH_SERVER_PORT=8989
LOCAL_SERVER_PORT=8080

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

This will create a tunnel from the DamageBDD server to your localhost. Any tests you submit referring to localhost will run against your local server.

3. Important Notes

Please note that this feature is still in the experimental phase and may change. If you encounter any issues or have feedback, please let us know.