Getting started

Install

On Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/bddkit/bddkit/main/install.sh | sh

On Windows PowerShell:

irm https://raw.githubusercontent.com/bddkit/bddkit/main/install.ps1 | iex

The installer puts a prebuilt binary from the latest release into ~/.local/bin (on Windows, %LOCALAPPDATA%\bddkit\bin).

Your first scenario

bddkit runs scenarios against whatever you declare as a resource: an HTTP API built in, and browsers, mobile apps, command-line tools and object storage through plugins. The smallest suite below uses the built-in HTTP steps.

Create bddkit.yaml next to the features you will write:

paths: [features]

resources:
  api:
    main:
      base_url: https://api.example.com/

Create features/users.feature:

Feature: users and their posts

  Scenario: a user's posts belong to that user
    Given the "Accept" request header is "application/json"
    When I request "/users/1" using HTTP GET
    Then the response code is 200
    And the response body contains JSON:
      """
      {"id": "@variableType(int)", "email": "@regExp(/^[^@]+@example\\.com$/)"}
      """
    And extract "id" from JSON as "userId"
    Given the query parameter "userId" is "<<userId>>"
    When I request "/posts" using HTTP GET
    Then the response code is 200
    And the response body is a JSON array of length 3
    And the JSON node "[0].userId" should exist

The scenario reads a user, checks the shape of its JSON, and then uses the user’s id to request that user’s posts. <<userId>> is a variable: a value saved in one step and used in a later one.

Run it

bddkit run

A passing run ends with files: 1, scenarios: 1, failed: 0. A failing scenario prints the last HTTP exchange in full, so you do not need a debug flag to see what was sent and received.

Exit codes

Code	Meaning
0	every scenario passed
1	a scenario failed
2	the run never started: a broken config, a step that does not exist, an undeclared resource

Code 2 means the suite itself is broken. CI can tell that apart from a failing test.

Next

• Reports for machine-readable output and CI.
• Plugins for browsers, mobile apps, command-line tools and object storage.
• Steps for every builtin step.