Skip to main content

HTTP traffic mocking and expectations made easy

Project description

pook Build Status PyPI Coverage Status Documentation Status Stability Code Climate Python Versions

Versatile, expressive and hackable utility library for HTTP traffic mocking and expectations in Python.

pook was heavily inspired in gock, its equivalent package for Go.

Note: still beta quality library please. Additional features, more examples and better test coverage are still pending.

Features

  • Simple, expressive and fluent API.

  • Provides both Pythonic and chainable DSL API styles.

  • Full-featured HTTP response definitions and expectations.

  • Matches any HTTP protocol primitive (URL, method, query params, headers, body…).

  • Full regular expressions capable mock expectations matching.

  • Supports multiple HTTP clients via interceptor adapters (works with most popular HTTP client implementations).

  • Supports JSON Schema body matching.

  • Configurable volatile, persistent or TTL limited mocks.

  • Works with any testing framework or engine (unittest, pytest, nosetests…).

  • Usable in both runtime and testing environments.

  • Can be used as decorator and/or via context managers.

  • Real networking mode with optional custom traffic filtering.

  • Map/filter mocks easily for generic or custom mock expectations.

  • First-class JSON & XML support.

  • Simulated raised error exceptions.

  • Network delay simulation (only available in aiohttp).

  • Pluggable and hackable API.

  • Does not support WebSocket.

  • Works with Python +2.7 and +3.0 (including PyPy).

  • Dependency-less (just 2 small dependencies for JSONSchema and XML comparison helpers)

Supported HTTP clients

Note: only recent HTTP client versions has been tested. Multiple versions can be supported, but the latest one will have always priority.

Installation

Using pip package manager:

pip install pook

Or install the latest sources from Github:

pip install -e git+git://github.com/h2non/pook.git#egg=pook

Getting started

See ReadTheDocs documentation:

Documentation Status

API

See annotated API reference documention.

Examples

See examples documentation for full featured code and use case examples.

Basic mocking:

import pook
import requests

@pook.activate
def test_my_api():
    mock = pook.get('http://twitter.com/api/1/foobar',
                    type='json',
                    json={'error': 'not found'})
    mock.reply(404, json={'error': 'foo'})

    resp = requests.get('http://twitter.com/api/1/foobar')
    assert resp.json() == {"error": "not found"}
    assert len(mock.calls) == 1
    assert mock.calls[0].request.url == 'http://twitter.com/api/1/foobar'
    assert mock.calls[0].response.text == '{"error": "not found"}'

Using the chainable API DSL:

import pook
import requests

@pook.on
def test_my_api():
    mock = (pook.get('http://twitter.com/api/1/foobar')
              .reply(404)
              .json({'error': 'not found'}))

    resp = requests.get('http://twitter.com/api/1/foobar')
    assert resp.json() == {"error": "not found"}
    assert len(mock.calls) == 1
    assert mock.calls[0].request.url == 'http://twitter.com/api/1/foobar'
    assert mock.calls[0].response.text == '{"error": "not found"}'

Using the decorator:

import pook
import requests

@pook.get('http://httpbin.org/status/500', reply=204)
@pook.get('http://httpbin.org/status/400', reply=200)
def fetch(url):
    return requests.get(url)

res = fetch('http://httpbin.org/status/400')
print('#1 status:', res.status_code)

res = fetch('http://httpbin.org/status/500')
print('#2 status:', res.status_code)

Simple unittest integration:

import pook
import unittest
import requests


class TestUnitTestEngine(unittest.TestCase):

    @pook.activate
    def test_request(self):
        pook.get('server.com/foo').reply(204)
        res = requests.get('http://server.com/foo')
        self.assertEqual(res.status_code, 204)

    def test_request_with_context_manager(self):
        with pook.use():
            pook.get('server.com/bar', reply=204)
            res = requests.get('http://server.com/bar')
            self.assertEqual(res.status_code, 204)

Using the context manager for isolated HTTP traffic interception blocks:

import pook
import requests

# Enable HTTP traffic interceptor
with pook.use():
    pook.get('http://httpbin.org/status/500', reply=204)

    res = requests.get('http://httpbin.org/status/500')
    print('#1 status:', res.status_code)

# Interception-free HTTP traffic
res = requests.get('http://httpbin.org/status/200')
print('#2 status:', res.status_code)

Example using Hy language (Lisp dialect for Python):

(import [pook])
(import [requests])

(defn request [url &optional [status 404]]
  (doto (.mock pook url) (.reply status))
  (let [res (.get requests url)]
    (. res status_code)))

(defn run []
  (with [(.use pook)]
    (print "Status:" (request "http://server.com/foo" :status 204))))

;; Run test program
(defmain [&args] (run))

Development

Clone the repository:

git clone git@github.com:h2non/pook.git

Install dependencies:

pip install -r requirements.txt requirements-dev.txt

Install Python dependencies:

make install

Lint code:

make lint

Run tests:

make test

Generate documentation:

make htmldocs

License

MIT - Tomas Aparicio

History

0.1.1 (2016-12-01)

  • fix: Python 2 dictionary iteration syntax.

  • feat(docs): add more examples.

  • fix(matchers): better regular expression comparison support.

0.1.0 (2016-11-30)

  • First version (still beta)

0.1.0-rc.1 (2016-11-27)

  • First release candidate version (still beta)

Download files

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

Source Distribution

pook-0.1.1.tar.gz (48.2 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page