PyShould is a Python DSL allowing to write expectations or assertions in almost natural language. The goal is to offer an expressive yet readable syntax to define the expectations in detail.
Under the hood it uses the PyHamcrest library of matchers to build complex matching predicates with ease and offer great explanations when there is a mismatch.
Its primary use case is in unit testing, replacing the need for Python's native
assertX methods. Its use is completely transparent to the unit testing runner
used, since mismatches are reported using the standard AssertionError.
If you don't want to mess with the code the easier way to install is with pip:
pip install pyshould
The installation procedure is based on setuptools so it's pretty simple to get going. In order to install from a checkout of the repository you can just issue the following command:
python setup.py install
Now you'll be able to access PyShould by importing the package pyshould. It's
designed to be used with a wildcard import although if you prefer you can just
import those DSL keywords you need. Here are some examples on different ways to import
the library in your code:
from pyshould import *
from pyshould import should
from pyshould import should, should_not, all_ofExpectations are defined in by using a subject-predicate form that mimics english natural language. Basically they take the form:
subject | should.predicate
Where subject is a python expression and predicate defines matchers and
expected values.
Any python expression can be used before should, although lambdas and other complex expressions should be enclosed in parens to ensure a proper interpretation.
Matchers in the predicate part can have an expected value, this value should be
given between parens, as with a normal method call. It will be used as an argument
to the matcher function. If the matcher doesn't require an expected value there is
no need to use it as a method call.
TIP Run the following to print all the configured expectations with a description of what they do:
python -m pyshould(usepython -m pyshould.__main__for Python 2.6)
See the following examples of expectations:
from pyshould import *
result | should.be_integer()
(1+1) | should_not.equal(1)
"foo" | should.equal('foo')
len([1,2,3]) | should.be_greater_than(2);
result | should.equal(1/2 + 5)
1 | should_not.eq(2)
# Matchers not requiring a param can skip the call parens
True | should.be_truthy
# Check for exceptions with the context manager interface
with should.throw(TypeError):
raise TypeError('foo')
with should.not_raise: # will report a failure
fp = open('does-not-exists.txt')
# Apply our custom logic for a test
'FooBarBaz' | should.pass_callback(lambda x: x[3:6] == 'Bar')Complex expectations can be coordinated by using operators and, or and
but. Also not is supported to negate the result of an expectation. It's
important to understand the operator precedence rules before using them,
although they try to follow common conventions for the english language there
might be cases where they don't quite do what they look like.
All operators are left-associative and take two operands, except for not which
is an unary operator, thus the precedence rules are very simple:
operator | precedence index
---------------------------------
not | 4
and | 3
or | 2
but | 1
Expectations should be kept simple, when in doubt break up complex expectations into simpler ones.
Please review the following examples to see how these precedence rules apply.
should.be_an_integer.or_string.and_equal(1)
# (integer) OR (string AND equal 1)
should.be_an_integer.or_a_float.or_a_string
# (integer) OR (float) OR (string)
should.be_an_integer.or_a_string.and_equal_to(10).or_a_float
# (integer) OR (string AND equal 10) OR (float)
should.be_an_integer.or_a_string.but_less_than(10)
# (integer OR string) AND (less than 10)
# Note: we can use spacing to make them easier to read
should.be_an_integer .or_a_string.and_equal(0) .or_a_float
# (integer) OR (string AND equal 0) OR (float)
# Note: in this case we use capitalization to make them more obvious
should.be_an_integer .Or_a_string.And_equal(1) .But_Not_be_a_float
# ( (integer) OR (string AND equal 1) ) AND (not float)
# Note: if no matchers are given the last one is used
should.be_equal_to(10).Or(20).Or(30)
# (equal 10) OR (equal 20) OR (equal 30)
# Note: If no combinator is given AND is used by default
should.integer.greater_than(10).less_than(20)
# (integer) AND (greater than 10) AND (less than 20)
# Note: But by using should_either we can set OR as default
should_either.equal(10).equal(20).equal(30)
# (equal 10) OR (equal 20) OR (equal 30)Using the standard syntax it's possible to define a matcher in conjunction with a quantifier. These are specially useful when working with iterable values.
[1, 2] | should_all.be_int
(1, 2) | should_any.equal(1)
iterable | should_none.be_emptyWe can also define directly a matcher without using the pipe syntax by wrapping the value to test in a quantifier keyword.
it(1).should_equal(1)
it(0).to_equal(0)
any_of(1, 3).to_equal(1)
all_of([1, 3]).should_be_int()
none_of(1, 3).to_eq(0)Besides the standard syntax shown above (aka pipe syntax) it's also possible
to use other syntaxes by using the expect module, although it doesn't support
coordinated expressions (use of and, or, but).
from pyshould.expect import expect, expect_all, expect_any, expect_none
expect(1).to_equal(1)
# Note that matchers without params need the call parens when using this syntax
expect_all(1, 3).to_be_int()
expect_any([1, 3]).to_equal(1)
expect(any_of(1,3)).to_equal(1)NOTE This is only supported when running under cpython.
Thanks to the great folks @clarete and @gabrielfalcao from
sure it's possible to patch the root
object to expose special properties for testing any value. To enable this
feature you must import the pyshould.patch module.
WARNING Once the
patchmodule is imported it will monkey patch the root object from which all variables are extended from in your Python runtime. This means that every object will be extended with the following properties:should,should_not,should_all,should_anyandshould_none.
import pyshould.patch
'foo'.should.eq('foo')
data = {'foo': 'bar'}
data.should_not.have_key('lorem')
data.keys().should_all.be_string()
Broadly speaking, pyshould expressions overload Python's equality operator, so it's possible to use them with almost any third party library. Here is an example of the integration with the standard unittest assertion library.
m = should.be_an_int.and_greater_than(3)
self.assertEqual(2, m)
# AssertionError: 2 != (an integer and a value greater than <3>)
Michael Foord's Mock, which is available
under unittest.mock from Python 3.3, will also work out of the box:
mock(10, 1)
mock.assert_called_with(should.any, should.be_greater_than(3))
# AssertionError: Expected call: mock(ANYTHING, a value greater than <3>)
Mockito has also been tested and works out of the box:
verify(MyClass).my_method(should.be_truthy, should.eq(10))
An useful feature when integrating the expectations with a mocking library is to be
able to transform a value before asserting it. This can be triggered by passing a
callable as only argument to a non initialized expression (ie: should(callable)).
For instance you've mocked a call that will receive a Json serialized string but you want to test if it contains a given key. Check the following example:
mock('{"username": "drslump", "password": "foobar"}')
mock.assert_called_with( should(json.loads).have_key('username') )
If you need to use the same transform often you could also create an expectation for it:
should_json = should(json.loads)
mock.assert_called_with( should_json.have_key('username') )
d | should_json.have_key('username')
Creating your custom expectations is fairly easy, have a look at the matchers.py
file for a set of examples. Basically expectations are just a thin layer of
syntax sugar over Hamcrest's matchers, so the most difficult part is to implement
the actual matcher.
Alternatively, for those cases where we just want to test something complicated
but not create a reusable matcher, it's possible to use the callback expectation:
def my_complex_assert(value):
# NOTE: we can also return an expectation instead of a bool
# ie: return value | should.eq(10).Or(20).but_be_greater_than(100)
resp = request.get('http://foo.com/bar', {'q': value})
return resp.status_code == 200
self.foo | should.pass_callback(my_complex_assert)
The pipe syntax has an incompatibility when the subject under tests has an
overloaded __or__ operator and is not a builtin type.
In those cases the only option is to use an alternative syntax for that test.
I find it extremely convenient to include should as a keyword under my editor
highlighting. This simple change makes the tests much more obvious and easier to
read. Here is an example syntax for Sublime Text, just place it in a file under
your user package directory.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>comment</key>
<string>Customizations to the Python syntax</string>
<key>name</key>
<string>Python (Customized)</string>
<key>scopeName</key>
<string>source.custom.python</string>
<key>fileTypes</key>
<array>
<string>py</string>
</array>
<key>patterns</key>
<array>
<dict>
<key>match</key>
<string>\|\s*should(_(any|all|none|not|either))?\.</string>
<key>name</key>
<string>keyword.custom.python</string>
</dict>
<dict>
<key>include</key>
<string>source.python</string>
</dict>
</array>
</dict>
</plist>
The MIT License
Copyright (c) 2012, 2013 Iván -DrSlump- Montes
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.