Skip to main content

HTTP assertion plugin for grappa

Project description

grappa logo

Build Status PyPI Coverage Status Documentation Status Stability Code Climate Python Versions Say Thanks


HTTP request/response assertion plugin for grappa. grappa-http extends grappa assertion operators with HTTP protocol testing.

To get started, take a look to the documentation, tutorial and examples.


grappa-http is still beta quality software.


import pook
import requests
from grappa_http import should

# Activate the HTTP mock engine

# Register a sample mock
pook.get('', reply=200,
         response_headers={'Server': 'nginx'},
         response_json={'foo': 'bar'})

# Perform HTTP request
res = requests.get('')

# Test response status to be OK
res |
# Or alternatively using the status code
res | should.have.status(200)

# Test request URL
res | should.have.url.hostname('')
res | should.have.url.port(80)
res | should.have.url.path('/foo')
res | should.have.url.query.params({'bar': 'baz'})

# Test response body MIME content type
res | should.have.content('json')

# Test response headers
(res | (should.have.header('Content-Type')'application/json')))
res | should.have.header('Server').that.should.contain('nginx')

# Test response body
res |'{\n    "foo": "bar"\n}')
res | should.have.body.that.contains('foo')

# Test response body length
res | should.have.body.length.of(20)
res | should.have.body.length.higher.than(10)

# Test response JSON body
res |{'foo': 'bar'})
res | should.have.json.have.key('foo') >'bar')

# Validate response JSON bodies using JSONSchema
res | should.implement.jsonschema({
    '$schema': '',
    'title': 'Response JSON',
    'type': 'object',
    'required': ['foo'],
    'properties': {
        'foo': {
            'description': 'foo always means foo',
            'type': 'string'

Full-featured error report example:

Traceback (most recent call last):
  File "grappa-http/tests/", line 38, in test_http_tutorial
    res |'{\n    "foo": "baa"\n}')
  File "grappa/grappa/", line 208, in __ror__
    return self.__overload__(value)
  File "grappa/grappa/", line 196, in __overload__
    return self.__call__(subject, overload=True)
  File "grappa/grappa/", line 73, in __call__
    return self._trigger() if overload else Test(subject)
  File "grappa/grappa/", line 113, in _trigger
    raise err
AssertionError: Oops! Something went wrong!

  The following assertion was not satisfied
    subject "{\n    "foo": "bar"\n}" should have body equal to "{\n    "foo": "baa"\n}"

  What we expected
    a response body data equal to:
            "foo": "baa"

  What we got instead
    a response body with data:
            "foo": "bar"

  Difference comparison
    >   {
    > -     "foo": "bar"
    > ?               ^
    > +     "foo": "baa"
    > ?               ^
    >   }

    File "grappa-http/tests/", line 38, in test_http_tutorial

    30|       res | should.have.content('json')
    32|       # Test response headers
    33|       (res | (should.have.header('Content-Type')
    34|     'application/json')))
    35|       res | should.have.header('Server').that.should.contain('nginx')
    37|       # Test response body
    38| >     res |'{\n    "foo": "baa"\n}')
    39|       res | should.have.body.that.contains('foo')
    41|       # Test response body length
    42|       res | should.have.body.length.of(20)
    43|       res | should.have.body.length.higher.than(10)
    45|       # Test response JSON body


  • Full-featured HTTP response assertions.
  • Supports any protocol primitive assertions.
  • First-class support for JSON body assertion.
  • Built-in JSONSchema validation.
  • Full-features request URL validation.
  • Featured regular expression based assertion.
  • Works with requests and aiohttp HTTP clients.
  • Friendly and detailed assertion error reporting with body diff comparisons.
  • Provides both expect and should assertion styles.
  • Testing framework agnostic. Works with unittest, nosetests, pytest, behave
  • Works with Python 2.6+, 3+, PyPy and possibly other Python implementations.

Supported HTTP clients


Using pip package manager:

pip install --upgrade grappa-http

Or install the latest sources from Github:

pip install -e git+git://


v0.1.3 / 2017-04-26

  • fix(adapters): use issubclass for adapter valid interface.

v0.1.2 / 2017-04-25

  • feat(api): add use_adapter() API for custom adapter registering
  • feat(jsonschema): update example which uses satisfy attribute operator

v0.1.1 / 2017-03-29

  • feat(requirements): upgrade grappa to latest version
  • feat(operators): add output size limit
  • feat(docs): add thanks badge
  • refactor(docs): update description
  • feat(examples): add featured example
  • fix(package): read version from grappa_http package
  • fix(docs): use grappa_http package

0.1.0 (2017-03-25)

  • First version (beta)

Download files

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

Files for grappa-http, version 0.1.3
Filename, size File type Python version Upload date Hashes
Filename, size grappa_http-0.1.3-py2.py3-none-any.whl (27.2 kB) File type Wheel Python version 3.6 Upload date Hashes View
Filename, size grappa-http-0.1.3.tar.gz (15.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page