sets¶

Comparing sets that aren’t the same will attempt to highlight where the differences lie:

>>> compare(set([1, 2]), set([2, 3]))
Traceback (most recent call last):
 ...
AssertionError: set not as expected:

in first but not second:
[1]

in second but not first:
[3]

dicts¶

Comparing dictionaries that aren’t the same will attempt to highlight where the differences lie:

>>> compare(dict(x=1, y=2, a=4), dict(x=1, z=3, a=5))
Traceback (most recent call last):
 ...
AssertionError: dict not as expected:

same:
['x']

in first but not second:
'y': 2

in second but not first:
'z': 3

values differ:
'a': 4 != 5

lists and tuples¶

Comparing lists or tuples that aren’t the same will attempt to highlight where the differences lie:

>>> compare([1, 2, 3], [1, 2, 4])
Traceback (most recent call last):
 ...
AssertionError: sequence not as expected:

same:
[1, 2]

first:
[3]

second:
[4]

namedtuples¶

When two namedtuple() instances are compared, if they are of the same type, the description given will highlight which elements were the same and which were different:

>>> from collections import namedtuple
>>> TestTuple = namedtuple('TestTuple', 'x y z')
>>> compare(TestTuple(1, 2, 3), TestTuple(1, 4, 3))
Traceback (most recent call last):
 ...
AssertionError: TestTuple not as expected:

same:
['x', 'z']

values differ:
'y': 2 != 4

generators¶

When two generators are compared, they are both first unwound into tuples and those tuples are then compared.

The generator helper is useful for creating a generator to represent the expected results:

>>> from testfixtures import generator
>>> def my_gen(t):
...     i = 0
...     while i<t:
...         i += 1
...         yield i
>>> compare(generator(1, 2, 3), my_gen(2))
Traceback (most recent call last):
 ...
AssertionError: sequence not as expected:

same:
(1, 2)

first:
(3,)

second:
()

strings and unicodes¶

Comparison of strings can be tricky, particularly when those strings contain multiple lines; spotting the differences between the expected and actual values can be hard.

To help with this, long strings give a more helpful representation when comparison fails:

>>> compare("1234567891011", "1234567789")
Traceback (most recent call last):
 ...
AssertionError:
'1234567891011'
!=
'1234567789'

Likewise, multi-line strings give unified diffs when their comparison fails:

>>> compare("""
...         This is line 1
...         This is line 2
...         This is line 3
...         """,
...         """
...         This is line 1
...         This is another line
...         This is line 3
...         """)
Traceback (most recent call last):
 ...
AssertionError:
--- first
+++ second
@@ -1,5 +1,5 @@

         This is line 1
-        This is line 2
+        This is another line
         This is line 3

Such comparisons can still be confusing as white space is taken into account. If you need to care about whitespace characters, you can make spotting the differences easier as follows:

>>> compare("\tline 1\r\nline 2"," line1 \nline 2", show_whitespace=True)
Traceback (most recent call last):
 ...
AssertionError:
--- first
+++ second
@@ -1,2 +1,2 @@
-'\tline 1\r\n'
+' line1 \n'
 'line 2'

However, you may not care about some of the whitespace involved. To help with this, compare() has two options that can be set to ignore certain types of whitespace.

If you wish to compare two strings that contain blank lines or lines containing only whitespace characters, but where you only care about the content, you can use the following:

compare('line1\nline2', 'line1\n \nline2\n\n',
        blanklines=False)

If you wish to compare two strings made up of lines that may have trailing whitespace that you don’t care about, you can do so with the following:

compare('line1\nline2', 'line1 \t\nline2   \n',
        trailing_whitespace=False)

Recursive comparison¶

Where compare() is able to provide a descriptive comparison for a particular type, it will then recurse to do the same for the elements contained within objects of that type. For example, when comparing a list of dictionaries, the description will not only tell you where in the list the difference occurred, but also what the differences were within the dictionaries that weren’t equal:

>>> compare([{'one': 1}, {'two': 2, 'text':'foo\nbar\nbaz'}],
...         [{'one': 1}, {'two': 2, 'text':'foo\nbob\nbaz'}])
Traceback (most recent call last):
 ...
AssertionError: sequence not as expected:

same:
[{'one': 1}]

first:
[{'text': 'foo\nbar\nbaz', 'two': 2}]

second:
[{'text': 'foo\nbob\nbaz', 'two': 2}]

While comparing [1]: dict not as expected:

same:
['two']

values differ:
'text': 'foo\nbar\nbaz' != 'foo\nbob\nbaz'

While comparing [1]['text']:
--- first
+++ second
@@ -1,3 +1,3 @@
 foo
-bar
+bob
 baz

This also applies to any comparers you have provided, as can be seen in the next section.

Providing your own comparers¶

When using compare() frequently for your own complex objects, it can be beneficial to give more descriptive output when two objects don’t compare as equal.

As an example, suppose you have a class whose instances have a timestamp and a name as attributes, but you’d like to ignore the timestamp when comparing:

from datetime import datetime

class MyObject(object):
    def __init__(self, name):
        self.timestamp = datetime.now()
        self.name = name

To compare lots of these, you would first write a comparer:

def compare_my_object(x, y, context):
    if x.name == y.name:
        return
    return 'MyObject named %s != MyObject named %s' % (
        context.label('x', repr(x.name)),
        context.label('y', repr(y.name)),
        )

Then you’d register that comparer for your type:

from testfixtures.comparison import register
register(MyObject, compare_my_object)

Now, it’ll get used when comparing objects of that type, even if they’re contained within other objects:

>>> compare([1, MyObject('foo')], [1, MyObject('bar')])
Traceback (most recent call last):
 ...
AssertionError: sequence not as expected:

same:
[1]

first:
[<MyObject ...>]

second:
[<MyObject ...>]

While comparing [1]: MyObject named 'foo' != MyObject named 'bar'

From this example, you can also see that a comparer can indicate that two objects are equal, for compare()‘s purposes, by returning None:

>>> MyObject('foo') == MyObject('foo')
False
>>> compare(MyObject('foo'), MyObject('foo'))

You can also see that you can, and should, use the context object passed in to add labels to the representations of the objects being compared if the comparison fails:

>>> compare(expected=MyObject('foo'), actual=MyObject('bar'))
Traceback (most recent call last):
 ...
AssertionError: MyObject named 'foo' (expected) != MyObject named 'bar' (actual)

It may be that you only want to use a comparer or set of comparers for a particular test. If that’s the case, you can pass compare() a comparers parameter consisting of a dictionary that maps types to comparers. These will be added to the global registry for the duration of the call:

>>> compare(MyObject('foo'), MyObject('bar'),
...         comparers={MyObject: compare_my_object})
Traceback (most recent call last):
 ...
AssertionError: MyObject named 'foo' != MyObject named 'bar'

A full list of the available comparers included can be found below the API documentation for compare(). These make good candidates for registering for your own classes, if they provide the necessary behaviour, and their source is also good to read when wondering how to implement your own comparers.

You may be wondering what the context object passed to the comparer is for; it allows you to hand off comparison of parts of the two objects currently being compared back to the compare() machinery, it also allows you to pass options to your comparison function.

For example, you may have an object that has a couple of dictionaries as attributes:

from datetime import datetime

class Request(object):
    def __init__(self, uri, headers, body):
        self.uri = uri
        self.headers = headers
        self.body = body

When your tests encounter instances of these that are not as expected, you want feedback about which bits of the request or response weren’t as expected. This can be achieved by implementing a comparer as follows:

def compare_request(x, y, context):
    uri_different = x.uri != y.uri
    headers_different = context.different(x.headers, y.headers, '.headers')
    body_different = context.different(x.body, y.body, '.body')
    if uri_different or headers_different or body_different:
        return 'Request for %r != Request for %r' % (
            x.uri, y.uri
        )

This comparer can either be registered globally or passed to each compare() call and will give detailed feedback about how the requests were different:

>>> compare(Request('/foo', {'method': 'POST'}, {'my_field': 'value_1'}),
...         Request('/foo', {'method': 'GET'}, {'my_field': 'value_2'}),
...         comparers={Request: compare_request})
Traceback (most recent call last):
 ...
AssertionError: Request for '/foo' != Request for '/foo'

While comparing .headers: dict not as expected:

values differ:
'method': 'POST' != 'GET'

While comparing .headers['method']: 'POST' != 'GET'

While comparing .body: dict not as expected:

values differ:
'my_field': 'value_1' != 'value_2'

While comparing .body['my_field']: 'value_1' != 'value_2'

As an example of passing options through to a comparer, suppose you wanted to compare all decimals in a nested data structure by rounding them to a number of decimal places that varies from test to test. The comparer could be implemented and registered as follows:

from decimal import Decimal
from testfixtures.comparison import register

def compare_decimal(x, y, context):
     precision = context.get_option('precision', 2)
     if round(x, precision) != round(y, precision):
         return '%r != %r when rounded to %i decimal places' % (
             x, y, precision
         )

register(Decimal, compare_decimal)

Now, this comparer will be used for comparing all decimals and the precision used will be that passed to compare():

>>> expected_order = {'price': Decimal('1.234'), 'quantity': 5}
>>> actual_order = {'price': Decimal('1.236'), 'quantity': 5}
>>> compare(expected_order, actual_order, precision=1)
>>> compare(expected_order, actual_order, precision=3)
Traceback (most recent call last):
 ...
AssertionError: dict not as expected:

same:
['quantity']

values differ:
'price': Decimal('1.234') != Decimal('1.236')

While comparing ['price']: Decimal('1.234') != Decimal('1.236') when rounded to 3 decimal places

If no precision is passed, the default of 2 will be used:

>>> compare(Decimal('2.006'), Decimal('2.009'))
>>> compare(Decimal('2.001'), Decimal('2.009'))
Traceback (most recent call last):
 ...
AssertionError: Decimal('2.001') != Decimal('2.009') when rounded to 2 decimal places

Strict comparison¶

If is it important that the two values being compared are of exactly the same type, rather than just being equal as far as Python is concerned, then the strict mode of compare() should be used.

For example, these two instances will normally appear to be equal provided the elements within them are the same:

>>> TypeA = namedtuple('A', 'x')
>>> TypeB = namedtuple('B', 'x')
>>> compare(TypeA(1), TypeB(1))

If this type difference is important, then the strict parameter should be used:

>>> compare(TypeA(1), TypeB(1), strict=True)
Traceback (most recent call last):
 ...
AssertionError: A(x=1) (<class '__main__.A'>) != B(x=1) (<class '__main__.B'>)

Types of comparison¶

There are several ways a comparison can be set up depending on what you want to check.

If you only care about the class of an object, you can set up the comparison with only the class:

>>> C(SomeClass) == SomeClass(1, 2)
True

This can also be achieved by specifying the type of the object as a dotted name:

>>> import sys
>>> C('types.ModuleType') == sys
True

Alternatively, if you happen to have a non-comparable object already around, comparison can be done with it:

>>> C(SomeClass(1,2)) == SomeClass(1,2)
True

If you only care about certain attributes, this can also easily be achieved with the strict parameter:

>>> C(SomeClass, x=1, strict=False) == SomeClass(1, 2)
True

The above can be problematic if you want to compare an object with attibutes that share names with parameters to the Comparison constructor. For this reason, you can pass the attributes in a dictionary:

>>> compare(C(SomeClass, {'strict':3}, strict=False), SomeClass(1, 2))
Traceback (most recent call last):
 ...
AssertionError:
  <C(failed):...SomeClass>
  strict:3 not in other
  </C> != <...SomeClass...>

Gotchas¶

There are a few things to be careful of when using comparisons:

• The default strict comparison cannot be used with a class such as the following:

  class NoVars(object):
       __slots__ = ['x']
  

  If you try, you will get an error that explains the problem:

  >>> C(NoVars, x=1) == NoVars()
  Traceback (most recent call last):
   ...
  TypeError: <NoVars object at ...> does not support vars() so cannot do strict comparison
  

  Comparisons can still be done with classes that don’t support vars(), they just need to be non-strict:

  >>> nv = NoVars()
  >>> nv.x = 1
  >>> C(NoVars, x=1, strict=False) == nv
  True
  

• If the object being compared has an __eq__ method, such as Django model instances, then the Comparison must be the first object in the equality check.

  The following class is an example of this:

  class SomeModel:
      def __eq__(self,other):
          if isinstance(other,SomeModel):
              return True
          return False
  

  It will not work correctly if used as the second object in the expression:

  >>> SomeModel()==C(SomeModel)
  False
  

  However, if the comparison is correctly placed first, then everything will behave as expected:

  >>> C(SomeModel)==SomeModel()
  True
  

• It probably goes without saying, but comparisons should not be used on both sides of an equality check:

  >>> C(SomeClass)==C(SomeClass)
  False
  

The context manager¶

If you’re using a version of Python where the with keyword is available, the context manager provided by TestFixtures can be used:

from testfixtures import Replacer

def test_function():
    with Replacer() as r:
        r.replace('testfixtures.tests.sample1.X.y',mock_y)
        print(X().y())

For the duration of the with block, the replacement is used:

>>> test_function()
mock y

The decorator¶

If you are working in a traditional unittest environment and want to replace different things in different test functions, you may find the decorator suits your needs better:

from testfixtures import replace

@replace('testfixtures.tests.sample1.X.y',mock_y)
def test_function():
    print(X().y())

When using the decorator, the replacement is used for the duration of the decorated callable’s execution:

>>> test_function()
mock y

If you need to manipulate or inspect the object that’s used as a replacement, you can add an extra parameter to your function. The decorator will see this and pass the replacement in it’s place:

from mock import Mock
from testfixtures import compare,replace

@replace('testfixtures.tests.sample1.X.y',Mock())
def test_function(m):
    m.return_value = 'mock y'
    print(X().y())
    compare(m.call_args_list,[((), {})])

The above still results in the same output:

>>> test_function()
mock y

Manual usage¶

If you want to replace something for the duration of a doctest or you want to replace something for every test in a TestCase, then you can use the Replacer manually.

The instantiation and replacement are done in the setUp function of the TestCase or passed to the DocTestSuite constructor:

>>> from testfixtures import Replacer
>>> r = Replacer()
>>> r.replace('testfixtures.tests.sample1.X.y',mock_y)

The replacement then stays in place until removed:

>>> X().y()
'mock y'

Then, in the tearDown function of the TestCase or passed to the DocTestSuite constructor, the replacement is removed:

>>> r.restore()
>>> X().y()
'original y'

Timezones¶

In many situations where you’re mocking out now() or utcnow() you’re not concerned about timezones, especially given that both methods will usually return datetime objects that have a tzinfo of None. However, in some applications it is important that now() and utcnow() return different times, as they would normally if the application is run anywhere other than the UTC timezone.

The best way to understand how to use test_datetime() in these situations is to think of the internal queue as being a queue of datetime objects at the current local time with a tzinfo of None, much as would be returned by now(). If you pass in a tz parameter to now() it will be applied to the value before it is returned in the same way as it would by datetime.datetime.now().

If you pass in a tzinfo to test_datetime(), this will be taken to indicate the timezone you intend for the local times that now() simulates. As such, that timezone will be used to compute values returned from utcnow() such that they would be test_datetime objects in the UTC timezone with the tzinfo set to None, as would be the case for a normal call to datetime.datetime.utcnow().

For example, lets take a timezone as defined by the following class:

from datetime import tzinfo, timedelta

class ATZInfo(tzinfo):

   def tzname(self, dt):
        return 'A TimeZone'

   def utcoffset(self, dt):
        # In general, this timezone is 5 hours behind UTC
        offset  = timedelta(hours=-5)
        return offset+self.dst(dt)

   def dst(self, dt):
        # However, between March and September, it is only
        # 4 hours behind UTC
        if 3 < dt.month < 9:
            return timedelta(hours=1)
        return timedelta()

If we create a test_datetime with this timezone and a delta of zero, so we can see affect of the timezone over multiple calls, the values returned by now() will be affected:

>>> datetime = test_datetime(2001, 1, 1, delta=0, tzinfo=ATZInfo())

A normal call to now() will return the values passed to the constructor:

>>> print(datetime.now())
2001-01-01 00:00:00

If we now ask for this time but in the timezone we passed to test_datetime, we will get the same hours, minutes and seconds but with a tzinfo attribute set:

>>> print(datetime.now(ATZInfo()))
2001-01-01 00:00:00-05:00

If we call utcnow(), we will get the time equivalent to the values passed to the constructor, but in the UTC timezone:

>>> print(datetime.utcnow())
2001-01-01 05:00:00

The timezone passed in when the test_datetime is created has a similar effect on any items set:

>>> datetime.set(2011,5,1,10)
>>> print(datetime.now())
2011-05-01 10:00:00
>>> print(datetime.utcnow())
2011-05-01 14:00:00

Likewise, add() behaves the same way:

>>> datetime = test_datetime(None, delta=0, tzinfo=ATZInfo())
>>> datetime.add(2011,1,1,10)
>>> datetime.add(2011,5,1,10)
>>> datetime.add(2011,10,1,10)
>>> print(datetime.now())
2011-01-01 10:00:00
>>> print(datetime.utcnow())
2011-05-01 14:00:00
>>> print(datetime.now())
2011-10-01 10:00:00

Local references to functions¶

There are situations where people may have obtained a local reference to the today() or now() methods, such as the following code from the testfixtures.tests.sample1 package:

from datetime import datetime,date

now = datetime.now

def str_now_2():
    return str(now())

today = date.today

def str_today_2():
    return str(today())

In these cases, you need to be careful with the replacement:

>>> from testfixtures import Replacer,test_datetime
>>> from testfixtures.tests.sample1 import str_now_2, str_today_2
>>> with Replacer() as r:
...    r.replace('testfixtures.tests.sample1.today',test_date().today)
...    r.replace('testfixtures.tests.sample1.now',test_datetime().now)
...    str_today_2()
...    str_now_2()
'2001-01-01'
'2001-01-01 00:00:00'

Use with code that checks class types¶

When using the above specialist mocks, you may find code that checks the type of parameters passed may get confused. This is because, by default, test_datetime and test_date return instances of the real datetime and date classes:

>>> from testfixtures import test_datetime
>>> from datetime import datetime
>>> tdatetime = test_datetime()
>>> issubclass(tdatetime, datetime)
True
>>> tdatetime.now().__class__
<...'datetime.datetime'>

The above behaviour, however, is generally what you want as other code in your application and, more importantly, in other code such as database adapters, may handle instances of the real datetime and date classes, but not instances of the test_datetime and test_date mocks.

That said, this behaviour can cause problems if you check the type of an instance against one of the mock classes. Most people might expect the following to return True:

>>> isinstance(tdatetime(2011, 1, 1), tdatetime)
False
>>> isinstance(tdatetime.now(), tdatetime)
False

If this causes a problem for you, then both datetime and date take a strict keyword parameter that can be used as follows:

>>> tdatetime = test_datetime(strict=True)
>>> tdatetime.now().__class__
<class 'testfixtures.tdatetime.tdatetime'>
>>> isinstance(tdatetime.now(), tdatetime)
True

You will need to take care that you have replaced occurrences of the class where type checking is done with the correct test_datetime or test_date. Also, be aware that the date() method of test_datetime instances will still return a normal date instance. If type checking related to this is causing problems, the type the date() method returns can be controlled as shown in the following example:

from testfixtures import test_date, test_datetime

date_type = test_date(strict=True)
datetime_type = test_datetime(strict=True, date_type=date_type)

With things set up like this, the date() method will return an instance of the date_type mock:

>>> somewhen = datetime_type.now()
>>> somewhen.date()
tdate(2001, 1, 1)
>>> _.__class__ is date_type
True

The context manager¶

If you’re using a version of Python where the with keyword is available, the context manager provided by TestFixtures can be used:

>>> import logging
>>> from testfixtures import LogCapture
>>> with LogCapture() as l:
...     logger = logging.getLogger()
...     logger.info('a message')
...     logger.error('an error')

For the duration of the with block, log messages are captured. The context manager provides a check method that raises an exception if the logging wasn’t as you expected:

>>> l.check(
...     ('root', 'INFO', 'a message'),
...     ('root', 'ERROR', 'another error'),
...     )
Traceback (most recent call last):
 ...
AssertionError: sequence not as expected:

same:
(('root', 'INFO', 'a message'),)

expected:
(('root', 'ERROR', 'another error'),)

actual:
(('root', 'ERROR', 'an error'),)

It also has a string representation that allows you to see what has been logged, which is useful for doc tests:

>>> print(l)
root INFO
  a message
root ERROR
  an error

The decorator¶

If you are working in a traditional unittest environment and only want to capture logging for a particular test function, you may find the decorator suits your needs better:

from testfixtures import log_capture

@log_capture()
def test_function(l):
    logger = logging.getLogger()
    logger.info('a message')
    logger.error('an error')

    l.check(
        ('root', 'INFO', 'a message'),
        ('root', 'ERROR', 'an error'),
        )

Manual usage¶

If you want to capture logging for the duration of a doctest or in every test in a TestCase, then you can use the LogCapture manually.

The instantiation and replacement are done in the setUp function of the TestCase or passed to the DocTestSuite constructor:

>>> from testfixtures import LogCapture
>>> l = LogCapture()

You can then execute whatever will log the messages you want to test for:

>>> from logging import getLogger
>>> getLogger().info('a message')

At any point, you can check what has been logged using the check method:

>>> l.check(('root', 'INFO', 'a message'))

Alternatively, you can use the string representation of the LogCapture:

>>> print(l)
root INFO
  a message

Then, in the tearDown function of the TestCase or passed to the DocTestSuite constructor, you should make sure you stop the capturing:

>>> l.uninstall()

If you have multiple LogCapture objects in use, you can easily uninstall them all:

>>> LogCapture.uninstall_all()

The check method¶

The LogCapture has a check() method that will compare the log messages captured with those you expect. Expected messages are expressed as three-element tuples where the first element is the name of the logger to which the message should have been logged, the second element is the string representation of the level at which the message should have been logged and the third element is the message that should have been logged after any parameter interpolation has taken place.

If things are as you expected, the method will not raise any exceptions:

>>> result = l.check(
...     ('root', 'INFO', 'start of block number 1'),
...     ('root', 'ERROR', 'error occurred'),
...     )

However, if the actual messages logged were different, you’ll get an AssertionError explaining what happened:

>>> l.check(('root', 'INFO', 'start of block number 1'))
Traceback (most recent call last):
 ...
AssertionError: sequence not as expected:

same:
(('root', 'INFO', 'start of block number 1'),)

expected:
()

actual:
(('root', 'ERROR', 'error occurred'),)

Printing¶

The LogCapture has a string representation that shows what messages it has captured. This can be useful in doc tests:

>>> print(l)
root INFO
  start of block number 1
root ERROR
  error occurred

This representation can also be used to check that no logging has occurred:

>>> empty = LogCapture()
>>> print(empty)
No logging captured

Inspecting¶

The LogCapture also keeps a list of the LogRecord instances it captures. This is useful when you want to check specifics of the captured logging that aren’t available from either the string representation or the check() method.

A common case of this is where you want to check that exception information was logged for certain messages:

>>> print(l.records[-1].exc_info)
(<... '...RuntimeError'>, RuntimeError('No code to run!',), <traceback object at ...>)

If you’re working in a unit test, the following code may be more appropriate:

from testfixtures import compare, Comparison as C

compare(C(RuntimeError('No code to run!')), l.records[-1].exc_info[1])

The context manager¶

If you’re using a version of Python where the with keyword is available, a TempDirectory can be used as a context manager:

>>> from testfixtures import TempDirectory
>>> with TempDirectory() as d:
...   d.write('test.txt', b'some foo thing')
...   foo2bar(d.path, 'test.txt')
...   d.read('test.txt')
'...'
b'some bar thing'

The decorator¶

If you are working in a traditional unittest environment and only work with files or directories in a particular test function, you may find the decorator suits your needs better:

from testfixtures import tempdir, compare

@tempdir()
def test_function(d):
    d.write('test.txt', b'some foo thing')
    foo2bar(d.path, 'test.txt')
    compare(d.read('test.txt'), b'some bar thing')

Manual usage¶

If you want to work with files or directories for the duration of a doctest or in every test in a TestCase, then you can use the TempDirectory manually.

The instantiation and replacement are done in the setUp function of the TestCase or passed to the DocTestSuite constructor:

>>> from testfixtures import TempDirectory
>>> d = TempDirectory()

You can then use the temporary directory for your testing:

>>> d.write('test.txt', b'some foo thing')
'...'
>>> foo2bar(d.path, 'test.txt')
>>> d.read('test.txt') == b'some bar thing'
True

Then, in the tearDown function of the TestCase or passed to the DocTestSuite constructor, you should make sure the temporary directory is cleaned up:

>>> d.cleanup()

If you have multiple TempDirectory objects in use, you can easily clean them all up:

>>> TempDirectory.cleanup_all()

Computing paths¶

If you need to know the real path of the temporary directory, the TempDirectory object has a path attribute:

>>> tempdir.path
'...tmp...'

A common use case is to want to compute a path within the temporary directory to pass to code under test. This can be done with the getpath() method:

>>> tempdir.getpath('foo').rsplit(os.sep,1)[-1]
'foo'

If you want to compute a deeper path, you can either pass either a tuple or a forward slash-separated path:

>>> tempdir.getpath(('foo', 'baz')).rsplit(os.sep, 2)[-2:]
['foo', 'baz']
>>> tempdir.getpath('foo/baz') .rsplit(os.sep, 2)[-2:]
['foo', 'baz']

Writing files¶

To write to a file in the root of the temporary directory, you pass the name of the file and the content you want to write:

>>> tempdir.write('myfile.txt', b'some text')
'...'
>>> with open(os.path.join(tempdir.path, 'myfile.txt')) as f:
...     print(f.read())
some text

The full path of the newly written file is returned:

>>> path = tempdir.write('anotherfile.txt', b'some more text')
>>> with open(path) as f:
...     print(f.read())
some more text

You can also write files into a sub-directory of the temporary directory, whether or not that directory exists, as follows:

>>> path = tempdir.write(('some', 'folder', 'afile.txt'), b'the text')
>>> with open(path) as f:
...     print(f.read())
the text

You can also specify the path to write to as a forward-slash separated string:

>>> path = tempdir.write('some/folder/bfile.txt', b'the text')
>>> with open(path) as f:
...     print(f.read())
the text

Creating directories¶

If you just want to create a sub-directory in the temporary directory you can do so as follows:

>>> tempdir.makedir('output')
'...'
>>> os.path.isdir(os.path.join(tempdir.path, 'output'))
True

As with file creation, the full path of the sub-directory that has just been created is returned:

>>> path = tempdir.makedir('more_output')
>>> os.path.isdir(path)
True

Finally, you can create a nested sub-directory even if the intervening parent directories do not exist:

>>> os.path.exists(os.path.join(tempdir.path, 'some'))
False
>>> path = tempdir.makedir(('some', 'sub', 'dir'))
>>> os.path.exists(path)
True

You can also specify the path to write to as a forward-slash separated string:

>>> os.path.exists(os.path.join(tempdir.path, 'another'))
False
>>> path = tempdir.makedir('another/sub/dir')
>>> os.path.exists(path)
True

Checking the contents of files¶

Once a file has been written into the temporary directory, you will often want to check its contents. This is done with the TempDirectory.read() method.

Suppose the code you are testing creates some files:

def spew(path):
   with open(os.path.join(path, 'root.txt'), 'wb') as f:
       f.write(b'root output')
   os.mkdir(os.path.join(path, 'subdir'))
   with open(os.path.join(path, 'subdir', 'file.txt'), 'wb') as f:
       f.write(b'subdir output')
   os.mkdir(os.path.join(path, 'subdir', 'logs'))

We can test this function by passing it the temporary directory’s path and then using the TempDirectory.read() method to check the files were created with the correct content:

>>> spew(tempdir.path)
>>> tempdir.read('root.txt')
b'root output'
>>> tempdir.read(('subdir', 'file.txt'))
b'subdir output'

The second part of the above test shows how to use the TempDirectory.read() method to check the contents of files that are in sub-directories of the temporary directory. This can also be done by specifying the path relative to the root of the temporary directory as a forward-slash separated string:

>>> tempdir.read('subdir/file.txt')
b'subdir output'

Checking the contents of directories¶

It’s good practice to test that your code is only writing files you expect it to and to check they are being written to the path you expect. TempDirectory.compare() is the method to use to do this.

As an example, we could check that the spew() function above created no extraneous files as follows:

>>> tempdir.compare([
...     'root.txt',
...     'subdir/',
...     'subdir/file.txt',
...     'subdir/logs/',
... ])

If we only wanted to check the sub-directory, we would specify the path to start from, relative to the root of the temporary directory:

>>> tempdir.compare([
...     'file.txt',
...     'logs/',
... ], path='subdir')

If, like git, we only cared about files, we could do the comparison as follows:

>>> tempdir.compare([
...     'root.txt',
...     'subdir/file.txt',
... ], files_only=True)

And finally, if we only cared about files at a particular level, we could turn off the recursive comparison as follows:

>>> tempdir.compare([
...     'root.txt',
...     'subdir',
... ], recursive=False)

The compare() method can also be used to check whether a directory contains nothing, for example:

>>> tempdir.compare(path=('subdir', 'logs'), expected=())

The above can also be done by specifying the sub-directory to be checked as a forward-slash separated path:

>>> tempdir.compare(path='subdir/logs', expected=())

If the actual directory contents do not match the expected contents passed in, an AssertionError is raised, which will show up as a unit test failure:

>>> tempdir.compare(['subdir'], recursive=False)
Traceback (most recent call last):
...
AssertionError: sequence not as expected:

same:
()

expected:
('subdir',)

actual:
('root.txt', 'subdir')

In some circumstances, you may want to ignore certain files or sub-directories when checking contents. To make this easy, the TempDirectory constructor takes an optional ignore parameter which, if provided, should contain a sequence of regular expressions. If any of the regular expressions return a match when used to search through the results of any of the the methods covered in this section, that result will be ignored.

For example, suppose we are testing some revision control code, but don’t really care about the revision control system’s metadata directories, which may or may not be present:

from random import choice

def svn_ish(dirpath, filename):
  if choice((True, False)):
    os.mkdir(os.path.join(dirpath, '.svn'))
  with open(os.path.join(dirpath, filename), 'wb') as f:
    f.write(b'something')

To test this, we can use any of the previously described methods.

When used manually or as a context manager, this would be as follows:

>>> with TempDirectory(ignore=['.svn']) as d:
...   svn_ish(d.path, 'test.txt')
...   d.compare(['test.txt'])

The decorator would be as follows:

from testfixtures import tempdir, compare

@tempdir(ignore=['.svn'])
def test_function(d):
    svn_ish(d.path, 'test.txt')
    d.compare(['test.txt'])

If you are working with doctests, the listdir() method can be used instead:

>>> tempdir.listdir()
root.txt
subdir
>>> tempdir.listdir('subdir')
file.txt
logs
>>> tempdir.listdir(('subdir', 'logs'))
No files or directories found.

The above example also shows how to check the contents of sub-directories of the temporary directory and also shows what is printed when a directory contains nothing. The listdir() method can also take a path separated by forward slashes, which can make doctests a little more readable. The above test could be written as follows:

>>> tempdir.listdir('subdir/logs')
No files or directories found.

However, if you have a nested folder structure, such as that created by our spew() function, it can be easier to just inspect the whole tree of files and folders created. You can do this by using the recursive parameter to listdir():

>>> tempdir.listdir(recursive=True)
root.txt
subdir/
subdir/file.txt
subdir/logs/

Bytes versus Strings¶

You’ll notice that all of the examples so far have used raw bytes as their data and written to and read from files only in binary mode. This keeps all the examples nice and simple and working consistently between Python 2 and Python 3. One of the big changes between Python 2 and Python 3 was that the default string type became unicode instead of binary, and a new type for bytes was introduced. This little snippet shows the difference by defining two constants for the British Pound symbol:

import sys
PY3 = sys.version_info[:2] >= (3, 0)

if PY3:
    some_bytes = '\xa3'.encode('utf-8')
    some_text = '\xa3'
else:
    some_bytes = '\xc2\xa3'
    some_text = '\xc2\xa3'.decode('utf-8')

Python 3 is much stricter than Python 2 about the byte versus string boundary and TempDirectory has been changed to help work with this by only reading and writing files in binary mode and providing parameters to control decoding and encoding when you want to read and write text.

For example, when writing, you can either write bytes directly, as we have been in the examples so far:

>>> path = tempdir.write('currencies.txt', some_bytes)
>>> with open(path, 'rb') as currencies:
...     currencies.read()
b'\xc2\xa3'

Or, you can write text, but must specify an encoding to use when writing the data to the file:

>>> path = tempdir.write('currencies.txt', some_text, 'utf-8')
>>> with open(path, 'rb') as currencies:
...     currencies.read()
b'\xc2\xa3'

The same is true when reading files. You can either read bytes:

>>> tempdir.read('currencies.txt') == some_bytes
True

Or, you can read text, but must specify an encoding that will be used to decode the data in the file:

>>> tempdir.read('currencies.txt', 'utf-8') == some_text
True

Setting up¶

To use the Manuel plugin, you need to make sure a TempDirectory instance is available under a particular name in the test globals. This name is then passed to the plugin’s constructor and the plugin is passed to Manuel’s TestSuite constructor.

The following example shows how to return a test suite that will execute all of the examples below. These require not only the TestFixtures plugin but also the Manuel plugins that give more traditional doctest behaviour, hidden code blocks that are useful for setting things up and checking examples without breaking up the flow of the documentation, and capturing of examples from the documentation to use for use in other forms of testing:

from glob import glob
from manuel import doctest, capture
from manuel.testing import TestSuite
from os.path import join
from testfixtures import TempDirectory
from testfixtures.manuel import Files

from . import compat

def setUp(test):
    test.globs['tempdir']=TempDirectory()

def tearDown(test): 
    test.globs['tempdir'].cleanup()

def test_suite():
    m = doctest.Manuel()
    m += compat.Manuel()
    m += capture.Manuel()
    m += Files('tempdir')
    return TestSuite(
        m,
        setUp=setUp,
        tearDown=tearDown,
        *glob(join(path_to_your_docs,'*.txt'))
        )

Writing files¶

To write a file with the plugin, a topic with a class of write-file is included in the documentation. The following example is a complete reStructuredText file that shows how to write a file that is then used by a later example:

Here's an example configuration file:

.. topic:: example.cfg
 :class: write-file

 ::

   [A Section]
   dir=frob
   long: this value continues
     on the next line

.. invisible-code-block: python
   
  from testfixtures.compat import PY3
  # change to the temp directory
  import os
  original_dir = os.getcwd()
  os.chdir(tempdir.path)

To parse this file using the :mod:`ConfigParser` module, you would
do the following:

.. code-block:: python

   if PY3:
       from configparser import ConfigParser
   else:
       from ConfigParser import ConfigParser
   config = ConfigParser()
   config.read('example.cfg')

The items in the section are now available as follows:

>>> for name, value in sorted(config.items('A Section')):
...     print('{0!r}:{1!r}'.format(name, value))
'dir':'frob'
'long':'this value continues\non the next line'

.. invisible-code-block: python
   
  # change out again
  import os
  os.chdir(original_dir)

Checking the contents of files¶

To read a file with the plugin, a topic with a class of read-file is included in the documentation. The following example is a complete reStructuredText file that shows how to check the values written by the code being documented while also using this check as part of the documentation:

.. invisible-code-block: python
   
  from testfixtures.compat import PY3
  # change to the temp directory
  import os
  original_dir = os.getcwd()
  os.chdir(tempdir.path)

To construct a configuration file using the :mod:`ConfigParser`
module, you would do the following: 

.. code-block:: python

   if PY3:
       from configparser import ConfigParser
   else:
       from ConfigParser import ConfigParser
   config = ConfigParser()
   config.add_section('A Section')
   config.set('A Section', 'dir', 'frob')
   f = open('example.cfg','w')
   config.write(f)
   f.close()

The generated configuration file will be as follows:

.. topic:: example.cfg
 :class: read-file

 ::

   [A Section]
   dir = frob

   
.. config parser writes whitespace at the end, be careful when testing!

.. invisible-code-block: python
   
  # change out again
  import os
  os.chdir(original_dir)

Checking the contents of directories¶

While the TestFixtures plugin itself does not offer any facility for checking the contents of directories, Manuel’s capture plugin can be used in conjunction with the existing features of a TempDirectory to illustrate the contents expected in a directory seamlessly within the documentation.

Here’s a complete reStructuredText document that illustrates this technique:

Here's an example piece of code that creates some files and
directories: 

.. code-block:: python

  import os

  def spew(path):
    with open(os.path.join(path, 'root.txt'), 'wb') as f:
        f.write(b'root output')
    os.mkdir(os.path.join(path, 'subdir'))
    with open(os.path.join(path, 'subdir', 'file.txt'), 'wb') as f:
        f.write(b'subdir output')
    os.mkdir(os.path.join(path, 'subdir', 'logs'))

This function is used as follows:

>>> spew(tempdir.path)

This will create the following files and directories::

  root.txt
  subdir/
  subdir/file.txt
  subdir/logs/
 
.. -> expected_listing

.. invisible-code-block: python

  # check the listing was as expected
  tempdir.compare(expected_listing.strip().split('\n'))

A note on encoding and line endings¶

As currently implemented, the plugin provided by TestFixtures only works with textual file content that can be encoded using the ASCII character set. This content will always be written with '\n' line seperators and, when read, will always have its line endings normalised to '\n'. If you hit any limitations caused by this, please raise an issue in the tracker on GitHub.