Expects Documentation

(1)

Expects Documentation

Release 0.2.2

Jaime Gil de Sagredo

May 20, 2014

(2)

(3)

Contents

1 Usage 3

2 Installation 5

3 Contents 7

3.1 Installation . . . 7

3.2 Reference. . . 7

3.3 Plugins . . . 22

3.4 Testing . . . 23

3.5 Changes . . . 24

4 Indices and tables 27

Python Module Index 29

(4)

(5)

Expects Documentation, Release 0.2.2

Expects is an expressive and extensible TDD/BDD assertion library for Python.

(6)

2 Contents

(7)

CHAPTER

1 Usage

Just import the expect callable and start writing test assertions.

from expects import expect expect([]).to.be.empty expect(False).not_to.be.true

expect({’name’: ’Jack’, ’email’: ’[email protected]’}).to.have.key(’name’) \ .with_value.match(’\w+’)

expect(str).to.have.property(’split’)

expect(lambda: foo).to.raise_error(NameError) You can see all the builtin assertions with lots of examples here.

(8)

4 Chapter 1. Usage

(9)

CHAPTER

2 Installation

You can install the last stable release of Expects from PyPI using pip or easy_install.

$ pip install expects

For more installation methods visit the installation guide.

(10)

6 Chapter 2. Installation

(11)

CHAPTER

3 3.1 Installation

You can install the last stable release of Expects from PyPI using pip or easy_install:

$ pip install expects

Or install the latest sources from Github:

$ pip install -e git+git://github.com/jaimegildesagredo/expects.git#egg=expects Also you can donwload a source code package fromGithuband install it using setuptools:

$ tar xvf expects-{version}.tar.gz

$ cd expects

$ python setup.py install

3.2 Reference

3.2.1 a

class Foo(object):

pass

class Bar(object):

pass

expect(Foo()).to.be.a(Foo) expect(Foo()).to.be.a(object) expect(Foo()).not_to.be.a(Bar) expect(Foo()).to.be.a(Bar)

Failure

Expected <Foo object at 0x7ff289cb4310> to be a Bar instance

(12)

expect(Foo()).not_to.be.a(object)

Failure

Expected <Foo object at 0x7ff289cb4310> not to be a object instance

expect(Foo()).not_to.be.a(Foo)

Failure

Expected <Foo object at 0x7ff289cb4310> not to be a Foo instance

3.2.2 above

expect(5).to.be.above(4) expect(1).not_to.be.above(4) expect(1).to.be.above(4)

Failure

Expected 1 to be above 4

expect(5).not_to.be.above(4)

Failure

Expected 5 not to be above 4

3.2.3 above_or_equal

expect(5).to.be.above_or_equal(4) expect(5).to.be.above_or_equal(5) expect(1).not_to.be.above_or_equal(4) expect(1).to.be.above_or_equal(4)

Failure

Expected 1 to be above or equal 4

expect(5).not_to.be.above_or_equal(4)

Failure

Expected 5 not to be above or equal 4

8 Chapter 3. Contents

(13)

expect(5).not_to.be.above_or_equal(5)

Failure

Expected 5 not to be above or equal 5

3.2.4 an

pass

class Object(object):

pass

expect(Foo()).to.be.an(object) expect(Foo()).not_to.be.an(Object) expect(Foo()).to.be.an(Object)

Failure

Expected <Foo object at 0x7ff289cb4310> to be an Object instance

expect(Foo()).not_to.be.an(object)

Failure

Expected <Foo object at 0x7ff289cb4310> not to be an object instance

3.2.5 be

pass

value = Foo()

expect(value).to.be(value) expect(1).not_to.be(2) expect(1).to.be(2)

Failure

Expected 1 to be 2

expect(value).not_to.be(value)

Failure

Expected <Foo object at 0x7ff289cb4310> not to be <Foo object at 0x7ff289cb4310>

(14)

3.2.6 below

expect(1).to.be.below(4) expect(4).not_to.be.below(1) expect(4).to.be.below(1)

Failure

Expected 4 to be below 1

expect(1).not_to.be.below(4)

Failure

Expected 1 not to be below 4

3.2.7 below_or_equal

expect(1).to.be.below_or_equal(4) expect(5).to.be.below_or_equal(5) expect(4).not_to.be.below_or_equal(1) expect(4).to.be.below_or_equal(1)

Failure

Expected 4 to be below or equal 1

expect(1).not_to.be.below_or_equal(4)

Failure

Expected 1 not to be below or equal 4

expect(5).not_to.be.below_or_equal(5)

Failure

Expected 5 not to be below or equal 5

3.2.8 empty

expect(’’).to.be.empty expect(iter(’’)).to.be.empty

(15)

expect(’foo’).not_to.be.empty expect(’foo’).to.be.empty

Failure

Expected ‘foo’ to be empty

expect(iter(’foo’)).to.be.empty

Failure

Expected <str_iterator object at 0x7fd4832d6950> to be empty

expect(’’).not_to.be.empty

Failure

Expected ‘’ not to be empty

3.2.9 equal

expect(1).to.equal(1) expect(1).not_to.equal(2) expect(1).to.equal(2)

Failure

Expected 1 to equal 2

expect(1).not_to.equal(1)

Failure

Expected 1 not to equal 1

3.2.10 false

expect(False).to.be.false expect(True).not_to.be.false expect(True).to.be.false

Failure

Expected True to be False

(16)

expect(False).not_to.be.false

Failure

Expected False not to be False

3.2.11 have

expect([’bar’, ’baz’]).to.have(’bar’)

expect([’bar’, ’baz’]).to.have(’bar’, ’baz’) expect([{’foo’: 1}, ’bar’]).to.have({’foo’: 1}) expect(iter([’bar’, ’baz’])).to.have(’bar’)

expect(iter([’bar’, ’baz’])).to.have(’bar’, ’baz’) expect(’My foo string’).to.have(’foo’)

expect(’My foo string’).to.have(’foo’, ’string’) expect([’bar’, ’baz’]).not_to.have(’foo’)

expect([’bar’, ’baz’]).not_to.have(’foo’, ’foobar’) expect([’bar’]).to.only.have(’bar’)

expect([’bar’, ’baz’]).to.only.have(’bar’, ’baz’) expect(’My foo string’).to.only.have(’My foo string’) expect(’My foo string’).to.only.have(’My foo’, ’ string’) expect([’bar’, ’baz’]).to.have(’bar’, ’foo’)

Failure

Expected [’bar’, ‘baz’] to have ‘foo’

expect(iter([’bar’, ’baz’])).to.have(’bar’, ’foo’)

Failure

Expected <listiterator object at 0x7ff289cb4310> to have ‘foo’

expect([’bar’, ’baz’]).not_to.have(’bar’, ’foo’)

Failure

Expected [’bar’, ‘baz’] not to have ‘bar’

expect([’bar’, ’baz’]).to.only.have(’foo’)

(17)

Failure

Expected [’bar’, ‘baz’] to only have ‘foo’

expect([’bar’, ’baz’]).to.only.have(’foo’, ’fuu’)

Failure

Expected [’bar’, ‘baz’] to only have ‘foo’ and ‘fuu’

expect([’bar’, ’baz’]).to.only.have(’bar’)

Failure

Expected [’bar’, ‘baz’] to only have ‘bar’

expect([’bar’, ’baz’]).to.only.have(’bar’, ’baz’)

Failure

Expected [’bar’, ‘baz’] to only have ‘bar’ and ‘baz’

expect([’bar’, ’baz’]).to.only.have(’bar’, ’baz’, ’foo’)

Failure

Expected [’bar’, ‘baz’] to only have ‘bar’, ‘baz’ and ‘foo’

expect(’My foo string’).to.only.have(’foo’)

Failure

Expected ‘My foo string’ to only have ‘foo’

3.2.12 key

expect({’bar’: 0, ’baz’: 1}).to.have.key(’bar’) expect({’bar’: 0, ’baz’: 1}).to.have.key(’bar’, 0) expect({’bar’: 0, ’baz’: 1}).not_to.have.key(’foo’) expect({’bar’: 0, ’baz’: 1}).not_to.have.key(’foo’, 0) expect({’bar’: 0, ’baz’: 1}).not_to.have.key(’bar’, 1) expect(’My foo string’).not_to.have.key(’foo’, 0)

expect({’bar’: 0, ’baz’: 1}).to.have.key(’bar’).with_value.equal(0) expect({’bar’: 0, ’baz’: 1}).to.have.key(’bar’).with_value.not_equal(1) expect({’bar’: 0, ’baz’: 1}).to.have.key(’foo’)

(18)

Failure

Expected {‘bar’: 0, ‘baz’: 1} to have key ‘foo’

expect({’bar’: 0, ’baz’: 1}).to.have.key(’foo’, 0)

Failure

expect({’bar’: 0, ’baz’: 1}).to.have.key(’bar’, 1)

Failure

Expected {‘bar’: 0, ‘baz’: 1} to have key ‘bar’ with value 1 but was 0

expect({’bar’: 0, ’baz’: 1}).to.have.key(’bar’, None)

Failure

Expected {‘bar’: 0, ‘baz’: 1} to have key ‘bar’ with value None but was 0

expect(’My foo string’).to.have.key(’foo’, 0)

Failure

Expected ‘My foo string’ to have key ‘foo’ but not a dict

expect({’bar’: 0, ’baz’: 1}).not_to.have.key(’bar’)

Failure

Expected {‘bar’: 0, ‘baz’: 1} not to have key ‘bar’

expect({’bar’: 0, ’baz’: 1}).not_to.have.key(’bar’, 0)

Failure

Expected {‘bar’: 0, ‘baz’: 1} not to have key ‘bar’ with value 0 but was 0

expect({’bar’: 0, ’baz’: 1}).to.have.key(’bar’).with_value.equal(1)

Failure

Expected {‘bar’: 0, ‘baz’: 1} to have key ‘bar’ with value 0 equal 1

expect({’bar’: 0, ’baz’: 1}).to.have.key(’bar’).with_value.not_equal(0)

Failure

Expected {‘bar’: 0, ‘baz’: 1} to have key ‘bar’ with value 0 not equal 0

(19)

3.2.13 keys

expect({’bar’: 0, ’baz’: 1}).to.have.keys(’bar’, ’baz’) expect({’bar’: 0, ’baz’: 1}).to.have.keys(bar=0, baz=1) expect({’bar’: 0, ’baz’: 1}).to.have.keys(’bar’, baz=1)

expect({’bar’: 0, ’baz’: 1}).to.have.keys({’bar’: 0, ’baz’: 1}) expect({’bar’: 0, ’baz’: 1}).not_to.have.keys(’foo’, ’foobar’) expect({’bar’: 0, ’baz’: 1}).not_to.have.keys(foo=0, foobar=1) expect({’bar’: 0, ’baz’: 1}).not_to.have.keys(foo=0, bar=1)

expect({’bar’: 0, ’baz’: 1}).not_to.have.keys({’foo’: 0, ’foobar’: 1}) expect({’bar’: 0, ’baz’: 1}).not_to.have.keys({’foo’: 0, ’bar’: 1}) expect({’bar’: 0, ’baz’: 1}).to.have.keys(’bar’, ’foo’)

Failure

expect({’bar’: 0, ’baz’: 1}).to.have.keys(bar=0, foo=1)

Failure

expect({’bar’: 0, ’baz’: 1}).to.have.keys(bar=1, baz=1)

Failure

expect({’bar’: 0, ’baz’: 1}).to.have.keys(’foo’, bar=0)

Failure

expect({’bar’: 0, ’baz’: 1}).to.have.keys(’baz’, bar=1)

Failure

expect({’bar’: 0, ’baz’: 1}).to.have.keys({’bar’: 1, ’baz’: 1})

Failure

(20)

expect({’bar’: 0, ’baz’: 1}).not_to.have.keys(’foo’, ’bar’)

Failure

expect({’bar’: 0, ’baz’: 1}).not_to.have.keys(baz=0, bar=0)

Failure

expect({’bar’: 0, ’baz’: 1}).not_to.have.keys(’bar’, baz=0)

Failure

expect({’bar’: 0, ’baz’: 1}).not_to.have.keys({’bar’: 0, ’foo’: 1})

Failure

3.2.14 length

expect(’foo’).to.have.length(3) expect(iter(’foo’)).to.have.length(3) expect(’foo’).not_to.have.length(2) expect(’foo’).to.have.length(2)

Failure

Expected ‘foo’ to have length 2 but was 3

expect(iter(’foo’)).to.have.length(2)

Failure

Expected <str_iterator object at 0x7fd4832d6950> to have length 2 but was 3

expect(’foo’).not_to.have.length(3)

Failure

Expected ‘foo’ not to have length 3 but was 3

(21)

3.2.15 match

expect(’My foo string’).to.match(r’My \w+ string’)

expect(’My foo string’).to.match(r’my [A-Z]+ strinG’, re.I) expect(’My foo string’).not_to.match(r’My \W+ string’) expect(’My foo string’).not_to.match(r’My \W+ string’, re.I) expect(’My foo string’).to.match(pattern)

Failure

Expected ‘My foo string’ to match r’My \W+ string’

expect(’My foo string’).not_to.match(r’My \w+ string’)

Failure

Expected ‘My foo string’ not to match r’My \w+ string’

3.2.16 none

expect(None).to.be.none expect(’foo’).not_to.be.none expect(True).to.be.none

Failure

Expected True to be None

expect(None).not_to.be.none

Failure

Expected None not to be None

3.2.17 properties

def __init__(self, **kwargs):

for name, value in kwargs.items():

setattr(self, name, value)

expect(Foo(bar=0, baz=1)).to.have.properties(’bar’, ’baz’) expect(Foo(bar=0, baz=1)).to.have.properties(bar=0, baz=1) expect(Foo(bar=0, baz=1)).to.have.properties(’bar’, baz=1)

(22)

expect(Foo(bar=0, baz=1)).to.have.properties({’bar’: 0, ’baz’: 1}) expect(Foo(bar=0, baz=1)).not_to.have.properties(’foo’, ’foobar’) expect(Foo(bar=0, baz=1)).not_to.have.properties(foo=0, foobar=1) expect(Foo(bar=0, baz=1)).not_to.have.properties(foo=0, bar=1)

expect(Foo(bar=0, baz=1)).not_to.have.properties({’foo’: 0, ’foobar’: 1}) expect(Foo(bar=0, baz=1)).not_to.have.properties({’foo’: 0, ’bar’: 1}) expect(Foo(bar=0, baz=1)).to.have.properties(’bar’, ’foo’)

Failure

Expected <Foo object at 0x7ff289cb4310> to have property ‘foo’

expect(Foo(bar=0, baz=1)).to.have.properties(bar=0, foo=1)

Failure

expect(Foo(bar=0, baz=1)).to.have.properties(bar=1, baz=1)

Failure

Expected <Foo object at 0x7ff289cb4310> to have property ‘bar’ with value 1 but was 0

expect(Foo(bar=0, baz=1)).to.have.properties(’foo’, bar=0)

Failure

expect(Foo(bar=0, baz=1)).to.have.properties(’baz’, bar=1)

Failure

expect(Foo(bar=0, baz=1)).to.have.properties({’bar’: 1, ’baz’: 1})

Failure

expect(Foo(bar=0, baz=1)).not_to.have.properties(’foo’, ’bar’)

Failure

Expected <Foo object at 0x7ff289cb4310> not to have property ‘bar’

(23)

expect(Foo(bar=0, baz=1)).not_to.have.properties(baz=0, bar=0)

Failure

Expected <Foo object at 0x7ff289cb4310> not to have property ‘bar’ with value 0 but was 0

expect(Foo(bar=0, baz=1)).not_to.have.properties(’bar’, baz=0)

Failure

expect(Foo(bar=0, baz=1)).not_to.have.properties(’foo’, bar=0)

Failure

expect(Foo(bar=0, baz=1)).not_to.have.properties({’bar’: 0, ’foo’: 1})

Failure

3.2.18 property

def __init__(self, **kwargs):

for name, value in kwargs.items():

setattr(self, name, value)

expect(Foo(bar=0, baz=1)).to.have.property(’bar’) expect(Foo(bar=0, baz=1)).to.have.property(’bar’, 0) expect(Foo(bar=0, baz=1)).not_to.have.property(’foo’) expect(Foo(bar=0, baz=1)).not_to.have.property(’foo’, 0) expect(Foo(bar=0, baz=1)).not_to.have.property(’bar’, 1)

expect(Foo(bar=0, baz=1)).to.have.property(’bar’).with_value.equal(0) expect(Foo(bar=0, baz=1)).to.have.property(’bar’).with_value.not_equal(1) expect(Foo(bar=0, baz=1)).to.have.property(’foo’)

Failure

expect(Foo(bar=0, baz=1)).to.have.property(’foo’, 0)

(24)

Failure

expect(Foo(bar=0, baz=1)).to.have.property(’bar’, 1)

Failure

expect(Foo(bar=0, baz=1)).to.have.property(’bar’, None)

Failure

Expected <Foo object at 0x7ff289cb4310> to have property ‘bar’ with value None but was 0

expect(Foo(bar=0, baz=1)).not_to.have.property(’bar’)

Failure

expect(Foo(bar=0, baz=1)).not_to.have.property(’bar’, 0)

Failure

expect(Foo(bar=0, baz=1)).to.have.property(’bar’).with_value.equal(1)

Failure

Expected <Foo object at 0x7ff289cb4310> to have property ‘bar’ with value 0 equal 1

expect(Foo(bar=0, baz=1)).to.have.property(’bar’).with_value.not_equal(0)

Failure

Expected <Foo object at 0x7ff289cb4310> to have property ‘bar’ with value 0 not equal 0

3.2.19 raise_error

def callback():

raise AttributeError(’error message’)

expect(callback).to.raise_error(AttributeError)

expect(callback).to.raise_error(AttributeError, ’error message’) expect(callback).to.raise_error(AttributeError, r’error \w+’) def callback():

raise AttributeError(2)

(25)

expect(callback).to.raise_error(AttributeError, 2) def callback():

raise KeyError()

expect(callback).to.raise_error(AttributeError)

Failure

Expected <function callback at 0x7fe70cb103b0> to raise AttributeError but KeyError raised

expect(lambda: None).to.raise_error(AttributeError)

Failure

Expected <function <lambda> at 0x7f3e670863b0> to raise AttributeError but not raised

def callback():

raise AttributeError(’bar’)

expect(callback).to.raise_error(AttributeError, ’foo’)

Failure

Expected <function callback at 0x7fe70cb103b0> to raise AttributeError with message ‘foo’ but message was ‘bar’

3.2.20 true

expect(True).to.be.true expect(False).not_to.be.true expect(False).to.be.true

Failure

Expected False to be True

expect(True).not_to.be.true

Failure

Expected True not to be True

3.2.21 within

expect(5).to.be.within(4, 7) expect(1).not_to.be.within(4, 7) expect(1).to.be.within(4, 7)

(26)

Failure

Expected 1 to be within 4, 7

expect(5).not_to.be.within(4, 7)

Failure

Expected 5 not to be within 4, 7

3.3 Plugins

3.3.1 Introduction

Expects is extensible via plugins. In fact, the builtin assertions is a plugin (the default one). Each plugin consists of a nameand a callable object which is the plugin itself.

To use an especific plugin we should call expect with the plugin name and the subject value as a keyword argument.

Doing this will return the result of calling the plugin callable. For example, a request plugin would look like this:

expect(request=my_request_obj).to.have.header(’Content-Type’)

The default plugin could also be called passing the subject value as a positional argument instead of passing its name as a keyword argument:

expect(default=’foo’).to.match(’\w+’) Will be the same that:

expect(’foo’).to.match(’\w+’)

Note: Clarify that the second option is the prefered way for using the builtin assertions (or default plugin).

3.3.2 Writing plugins

As said above, a plugin consists of a name and a callable object that should return the plugin instance. The name will be the name that we give it when we register the plugin (see below). The callable object, which can be a class or a function that returns an object, should receive the subject of the expectation as the first positional argument. Also it should receive a set of positional arguments that will be the initial failure message parts.

Let’s start writing our plugin callable:

class MyPlugin(object):

def __init__(self, actual, *message):

self.actual = actual self.message = message

When the plugin has been registered and we call expect(my_plugin=’foo’) the resulting object will the be same as if we instantiate the MyPlugin class as follows:

MyPlugin(’foo’, ’Expected’, ’my_plugin’)

(27)

Now that we have our initial plugin class we need to register it so we can use it with the expect(my_plugin=...) syntax. To to that we should usesetuptools to distributeour plugin and add the followingentry pointto the setup.py file:

setup(

[...]

entry_points={

’expects.plugins’: [

’my_plugin = my_plugin_module:MyPlugin’

] } )

Then we just need to install our plugin via setuptools and import expect to start writing assertions with it:

from expects import expect expect(’foo’).to.have.length(3)

expect(my_plugin=’foo’).to.wathever.you.want

Note: To a more-in-depth view of how a real plugin can be written take a look at thedefault plugin source code.

3.4 Testing

Thetestingmodule provides helpers to ease testing of your expects plugins.

class testing.failure(actual, message)

Thefailurecontext manager can be used to build assertions of your expectations failures. It tests that an expectation fails raising an AssertionError with the proper failure message.

Receives the object that is being asserted and a string that should match the failure message.

If the expectation does not raise an AssertionError or the failure message does not match then raises an AssertionError.

Examples:

>>> obj = object()

>>> with failure(obj, "to have property ’foo’"):

... expect(obj).to.have.property(’foo’)

>>> with failure(obj, "to have property ’__class__’"):

... expect(obj).to.have.property(’__class__’) Traceback (most recent call last):

File "<stdin>", line 2, in <module>

File "expects/testing.py", line 40, in __exit__

raise AssertionError(’Expected AssertionError to be raised’) AssertionError: Expected AssertionError to be raised

(28)

3.5 Changes

3.5.1 0.2.2 (May 20, 2014)

Bug fixes

• to.raise_error now works with a non-string object as second arg. See docs for examples.

3.5.2 0.2.1 (Mar 22, 2014)

Highlights

• Added a testing module with the failure contextmanager.

• Added a matchers module and the key matcher.

Bug fixes

• to.have and to.only.have now work properly when actual is a string.

3.5.3 0.2.0 (Feb 5, 2014)

Highlights

• Added initial plugins support. Seeplugins docsfor more info.

• The key and property expectations now return a new Expects object that can be used to chain expectations.

• Now every expectation part can be prefixed with not_ in order to negate an expectation. Ex:

expect(’foo’).not_to.be.emptyis the same than expect(’foo’).to.not_be.empty.

• Added the only.have expectation to test that the subject only has the given items.

Backwards-incompatible

• The greater_than, greater_or_equal_to, less_than and less_or_equal_to expectations are renamed to above, above_or_equal, below and below_or_equal.

3.5.4 0.1.1 (Ago 20, 2013)

Bug fixes

• to.have when iterable items are not hashable (Issue #8).

• to.have.key weird behavior when actual is not a dict (Issue #10).

(29)

3.5.5 0.1.0 (Ago 11, 2013)

Highlights

• First expects release.

(30)

(31)

CHAPTER

4 Indices and tables

• genindex

• modindex

• search

(32)

28 Chapter 4. Indices and tables

(33)

Python Module Index

t

testing,23