bddrest

Toolchain to define and verify REST API in BDD.

Quick start
Command Line Interface
- Enabling the bash autocompletion for bddrest

Quick start

Writing tests

Using Given, when, functions as you see in the example below, you can determine and assert the behaviour of your REST API.

The story, response, status objects are some proxies for currently writing story(inside the with Given( ... ): context) and it's response. and the last response after a Given and or when.

import re
import sys
import json

from bddrest.authoring import Given, when, response, status


def wsgi_application(environ, start_response):
    path = environ['PATH_INFO']
    if path.endswith('/None'):
        start_response(
            '404 Not Found',
            [('Content-Type', 'text/plain;charset=utf-8')]
        )
        yield b''
    else:
        start_response(
            '200 OK',
            [('Content-Type', 'application/json;charset=utf-8')]
        )
        result = json.dumps(dict(
            foo='bar'
        ))
        yield result.encode()


with Given(
        wsgi_application,
        title='Quickstart!',
        path='/books/id: 1',
        as_='visitor') as story:

    assert status == 200
    assert status == '200 OK'
    assert 'foo' in response.json
    assert response.json['foo'] == 'bar'

    when(
        'Trying invalid book id',
        path_parameters={'id': None}
    )

    assert response.status == 404

Dumping a `Story`

story.dumps()

Produces:

base_call:
  as_: visitor
  description: As a member I have to POST a book to the library.
  form:
    name: BDD Book
  query:
    a: b
  response:
    headers:
    - 'Content-Type: application/json;charset=utf-8'
    json:
      foo: bar
    status: 200 OK
  title: Posting a book
  path: /books/:id
  path_parameters:
    id: '1'
  verb: GET
calls:
- response:
    headers:
    - 'Content-Type: text/plain;charset=utf-8'
    status: 404 Not Found
  title: Trying invalid book id
  path_parameters:
    id: None

You may load the story again from this yaml with Story.loads(yaml).

There are two additional methods available to dump and load to and from a file: story.load(file) and story.dump(file)

Auto Dumping

You may pass the autodump argument of the Given function to configure the auto-dumping:

:param autodump: A file-like object to write dumped story.
                 Default is `None`, means autodump is disabled by default.

Auto Documentation

You may pass the autodoc argument of the Given function to configure the auto-documentation:

:param autodoc: A file-like object to write documentation.
                Default is `None`, meana autodoc is disabled by default.
:param autodoc_format: Either ``markdown`` or ``html``. default is
                       ``markdown``.

Markdown

You can use story.document([formatter_factory=MarkdownFormatter]) to generate documentation in arbitrary format for example: Markdown.

There is also a CLI to do this:

bddrest document < story.yml > story.md

## Posting a book

### GET /books/:id

As a member I have to POST a book to the library.

### Path Parameters

Name | Example
--- | ---
id | 1

### Query Strings

Name | Example
--- | ---
a | b

### Form

Name | Example
--- | ---
name | BDD Book

### Response: 200 OK

#### Headers

* Content-Type: application/json;charset=utf-8

#### Body

```json
{"foo": "bar"}
```

## WHEN: Trying invalid book id

### Path Parameters

Name | Example
--- | ---
id | None

### Response: 404 Not Found

#### Headers

* Content-Type: text/plain;charset=utf-8

Command Line Interface

After installing the project a command named bddrest will be available.

bddrest -h

Enabling the bash autocompletion for bddrest

Add this into your .bashrc and or $VIRTUAL_ENV/bin/postactivate.

eval "$(register-python-argcomplete bddrest)"

Metadata

Release files for bddrest 6.3.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bddrest 6.3.3
File	Size	Uploaded	Provenance
bddrest-6.3.3.tar.gz	30.5 kB	Apr 10, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for bddrest 6.3.3
File	Interpreter	ABI	Platform	Reset
bddrest-6.3.3-py3-none-any.whl 25.7 kB Apr 10, 2026 Without provenance	Python 3	none	any	Details

Total release size: 56.2 kB

Release files / bddrest-6.3.3.tar.gz

Download URL	bddrest-6.3.3.tar.gz
Size	30.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`9460e9c1ffc48138132851cd8de99edbcda83b52aee9f9b4595a9f650c3edc6e`
BLAKE2b-256 checksum How to use checksums	`b3b3b089aa3feb73ae65cbe12eb9f22ef2ae5187eaf16b3ad26c9e46a2823844`
Upload date	Apr 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Release files / bddrest-6.3.3-py3-none-any.whl

Download URL	bddrest-6.3.3-py3-none-any.whl
Size	25.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8c326ee42f8882d64183ced3bd5952e2309acafeada0992d765247863e6cbaf1`
BLAKE2b-256 checksum How to use checksums	`937e07b1cb9a3be10243dd88bad7edfb6b954ed3675def79bade702c5399ce87`
Upload date	Apr 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Security for bddrest 6.3.3

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.