Skip to main content

A toolchain for testing REST APIs in BDD manner.

Project description


Toolchain to define and verify REST API in BDD.

PyPI Status Build Status Coverage Status

Table of Contents

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'):
            '404 Not Found',
            [('Content-Type', 'text/plain;charset=utf-8')]
        yield b''
            '200 OK',
            [('Content-Type', 'application/json;charset=utf-8')]
        result = json.dumps(dict(
        yield result.encode()

with Given(
        url='/books/id: 1',
        as_='visitor') as story:

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

        'Trying invalid book id',
        url_parameters={'id': None}

    assert response.status == 404

Dumping a Story



  as_: visitor
  description: As a member I have to POST a book to the library.
    name: BDD Book
    a: b
    - 'Content-Type: application/json;charset=utf-8'
      foo: bar
    status: 200 OK
  title: Posting a book
  url: /books/:id
    id: '1'
  verb: GET
- response:
    - 'Content-Type: text/plain;charset=utf-8'
    status: 404 Not Found
  title: Trying invalid book id
    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 string which indicates the filename to dump the story, or
                 a `callable(story) -> filename` to determine the filename.
                 A file-like object is also accepted.
                 Default is `None`, meana autodumping is disabled by default.

Auto Documentation

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

:param autodoc: A string which indicates the name of documentation file, or
                 a `callable(story) -> filename` to determine the filename.
                 A file-like object is also accepted.
                 Default is `None`, meana autodoc is disabled by default.
                 Currently only markdown is supprted.


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 >
## Posting a book

### GET /books/:id

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

### Url 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

{"foo": "bar"}

## WHEN: Trying invalid book id

### Url 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)"

Mockup server

When you want serve the server for special yaml file using like below.

bddrest mockupserver yamlfilename

Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for bddrest, version 2.5.5
Filename, size & hash File type Python version Upload date
bddrest-2.5.5.tar.gz (18.7 kB) View hashes Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page