API Reference

class testfixtures.Comparison(object_or_type, attribute_dict=None, strict=True, **attributes)

These are used when you need to compare objects that do not natively support comparison.

Parameters:

• object_or_type – The object or class from which to create the Comparison.
• attribute_dict – An optional dictionary containing attibutes to place on the Comparison.
• strict – If true, any expected attributes not present or extra attributes not expected on the object involved in the comparison will cause the comparison to fail.
• attributes – Any other keyword parameters passed will placed as attributes on the Comparison.

class testfixtures.LogCapture(names=None, install=True, level=1)

These are used to capture entries logged to the Python logging framework and make assertions about what was logged.

Parameters:

• names – A sequence of strings containing the dotted names of loggers to capture. By default, the root logger is captured.
• install – If True, the LogCapture will be installed as part of its instantiation.

check(*expected)

This will compare the captured entries with the expected entries provided and raise an AssertionError if they do not match.

Parameters:expected – A sequence of 3-tuples containing the expected log entries. Each tuple should be of the form (logger_name, string_level, message)

clear()

Clear any entries that have been captured.

install()

Install this LogHandler into the Python logging framework for the named loggers.

This will remove any existing handlers for those loggers and drop their level to 1 in order to capture all logging.

uninstall()

Un-install this LogHandler from the Python logging framework for the named loggers.

This will re-instate any existing handlers for those loggers that were removed during installation and retore their level that prior to installation.

classmethod uninstall_all()

This will uninstall all existing LogHandler objects.

class testfixtures.OutputCapture

A context manager for capturing output to the sys.stdout and sys.stderr streams.

captured

A property containing any output that has been captured so far.

compare(expected)

Compare the captured output to that expected. If the output is not the same, an AssertionError will be raised.

Parameters:expected – A string containing the expected output.

disable()

Disable the output capture if it is enabled.

enable()

Enable the output capture if it is disabled.

class testfixtures.Replacer

These are used to manage the mocking out of objects so that units of code can be tested without having to rely on their normal dependencies.

replace(target, replacement, strict=True)

Replace the specified target with the supplied replacement.

Parameters:

• target – A string containing the dotted-path to the object to be replaced. This path may specify a module in a package, an attribute of a module, or any attribute of something contained within a module.
• replacement – The object to use as a replacement.
• strict – When True, an exception will be raised if an attempt is made to replace an object that does not exist.

restore()

Restore all the original objects that have been replaced by calls to the replace() method of this Replacer.

class testfixtures.ShouldRaise(exception=None)

This context manager is used to assert that an exception is raised within the context it is managing.

Parameters:exception –

This can be one of the following:

• None, indicating that an exception must be raised, but the type is unimportant.
• An exception class, indicating that the type of the exception is important but not the parameters it is created with.
• An exception instance, indicating that an exception exactly matching the one supplied should be raised.

class testfixtures.StringComparison(regex_source)

An object that can be used in comparisons of expected and actual strings where the string expected matches a pattern rather than a specific concrete string.

Parameters:regex_source – A string containing the source for a regular expression that will be used whenever this StringComparison is compared with any basestring instance.

class testfixtures.TempDirectory(ignore=(), create=True, path=None)

A class representing a temporary directory on disk.

Parameters:

• ignore – A sequence of strings containing regular expression patterns that match filenames that should be ignored by the TempDirectory listing and checking methods.
• create – If True, the temporary directory will be created as part of class instantiation.
• path – If passed, this should be a string containing a physical path to use as the temporary directory. When passed, TempDirectory will not create a new directory to use.

makedir(dirpath)

Make an empty directory at the specified path within the temporary directory. Any intermediate subdirectories that do not exist will also be created.

Parameters:dirpath –

The directory to create, which can be:

• A tuple of strings.
• A forward-slash separated string.

Returns:The full path of the created directory.

write(filepath, data)

Write the supplied data to a file at the specified path within the temporary directory. Any subdirectories specified that do not exist will also be created.

The file will always be written in binary mode.

Parameters:

• filepath –

  The path to the file to create, which can be:

  • A tuple of strings.
  • A forward-slash separated string.
• data – A string containing the data to be written.

Returns:

The full path of the file written.

check(*expected)

Compare the contents of the temporary directory with the expected contents supplied.

This method only checks the root of the temporary directory.

Parameters:expected – A sequence of strings containing the names expected in the directory.

check_all(dir, *expected)

Recursively compare the contents of the specified directory with the expected contents supplied.

Parameters:

• dir –

  The directory to check, which can be:

  • A tuple of strings, indicating that the elements of the tuple should be used as directory names to traverse from the root of the temporary directory to find the directory to be checked.
  • A forward-slash separated string, indicating the directory or subdirectory that should be traversed to from the temporary directory and checked.
  • An empty string, indicating that the whole temporary directory should be checked.
• expected – A sequence of strings containing the paths expected in the directory. These paths should be forward-slash separated and relative to the root of the temporary directory.

check_dir(dir, *expected)

Compare the contents of the specified subdirectory of the temporary directory with the expected contents supplied.

This method will only check the contents of the subdirectory specified and will not recursively check subdirectories.

Parameters:

• dir –

  The subdirectory to check, which can be:

  • A tuple of strings, indicating that the elements of the tuple should be used as directory names to traverse from the root of the temporary directory to find the directory to be checked.
  • A forward-slash separated string, indicating the directory or subdirectory that should be traversed to from the temporary directory and checked.
• expected – A sequence of strings containing the names expected in the directory.

cleanup()

Delete the temporary directory and anything in it. This TempDirectory cannot be used again unless create() is called.

classmethod cleanup_all()

Delete all temporary directories associated with all TempDirectory objects.

create()

Create a temporary directory for this instance to use if one has not already been created.

getpath(path)

Return the full path on disk that corresponds to the path relative to the temporary directory that is passed in.

Parameters:path –

The path to the file to create, which can be:

• A tuple of strings.
• A forward-slash separated string.

Returns:A string containing the full path.

listdir(path=None, recursive=False)

Print the contents of the specified directory.

Parameters:

• path –

  The path to list, which can be:

  • None, indicating the root of the temporary directory should be listed.
  • A tuple of strings, indicating that the elements of the tuple should be used as directory names to traverse from the root of the temporary directory to find the directory to be listed.
  • A forward-slash separated string, indicating the directory or subdirectory that should be traversed to from the temporary directory and listed.
• recursive – If True, the directory specified will have its subdirectories recursively listed too.

path = None

The physical path of the TempDirectory on disk

read(filepath, mode='rb')

Reading the file at the specified path within the temporary directory.

The file is always read in binary mode.

Parameters:

• filepath –

  The path to the file to read, which can be:

  • A tuple of strings.
  • A forward-slash separated string.
• mode – The mode used to open the file. Set to r if you’re reading and text file and not concerned about line endings. Leave the default in other cases.

Returns:

A string containing the data read.

testfixtures.compare(x, y, registry=None, strict=False, **kw)

Compare the two supplied arguments and raise an AssertionError if they are not the same. The AssertionError raised will attempt to provide descriptions of the differences found.

Any keywords parameters supplied will be passed to the function that ends up doing the comparison. See the API documentation below for details of these.

Parameters:

• registry – If supplied, should be a dictionary mapping types to comparer functions for those types. This will be used instead of the global comparer registry.
• strict – If True, objects will only compare equal if they are of the same type as well as being equal. Defaults to False.

testfixtures.comparison.register(type, comparer)

Register the supplied comparer for the specified type. This registration is global and will be in effect from the point this function is called until the end of the current process.

testfixtures.comparison.compare_sequence(x, y)

Returns a textual description of the differences between the two supplied sequences.

testfixtures.comparison.compare_generator(x, y)

Returns a textual description of the differences between the two supplied generators.

This is done by first unwinding each of the generators supplied into tuples and then passing those tuples to compare_sequence().

testfixtures.comparison.compare_dict(x, y)

Returns a textual description of the differences between the two supplied dictionaries.

testfixtures.comparison.compare_set(x, y)

Returns a textual description of the differences between the two supplied sets.

testfixtures.comparison.compare_text(x, y, blanklines=True, trailing_whitespace=True, show_whitespace=False)

Returns an informative string describing the differences between the two supplied strings. The way in which this comparison is performed can be controlled using the following parameters:

Parameters:

• blanklines – If False, then when comparing multi-line strings, any blank lines in either argument will be ignored.
• trailing_whitespace – If False, then when comparing multi-line strings, trailing whilespace on lines will be ignored.
• show_whitespace – If True, then whitespace characters in multi-line strings will be replaced with their representations.

testfixtures.diff(x, y)

A shorthand function that uses difflib to return a string representing the differences between the two string arguments.

Most useful when comparing multi-line strings.

testfixtures.generator(*args)

A utility function for creating a generator that will yield the supplied arguments.

testfixtures.log_capture(*names, **kw)

A decorator for making a LogCapture installed an available for the duration of a test function.

Parameters:names – An optional sequence of names specifying the loggers to be captured. If not specified, the root logger will be captured.

testfixtures.replace(target, replacement, strict=True)

A decorator to replace a target object for the duration of a test function.

Parameters:

• target – A string containing the dotted-path to the object to be replaced. This path may specify a module in a package, an attribute of a module, or any attribute of something contained within a module.
• replacement – The object to use as a replacement.
• strict – When True, an exception will be raised if an attempt is made to replace an object that does not exist.

class testfixtures.should_raise(exception=None)

A decorator to assert that the decorated function will raised an exception. An exception class or exception instance may be passed to check more specifically exactly what exception will be raised.

Parameters:exception –

This can be one of the following:

• None, indicating that an exception must be raised, but the type is unimportant.
• An exception class, indicating that the type of the exception is important but not the parameters it is created with.
• An exception instance, indicating that an exception exactly matching the one supplied should be raised.

testfixtures.tempdir(*args, **kw)

A decorator for making a TempDirectory available for the duration of a test function.

All arguments and parameters are passed through to the TempDirectory constructor.

testfixtures.test_date(year=2001, month=1, day=1, delta=None, delta_type='days', strict=False)

A function that returns a mock object that can be used in place of the datetime.date class but where the return value of today() can be controlled.

If a single positional argument of None is passed, then the queue of dates to be returned will be empty and you will need to call set() or add() before calling today().

Parameters:

• year – An optional year used to create the first date returned by today().
• month – An optional month used to create the first date returned by today().
• day – An optional day used to create the first date returned by today().
• delta – The size of the delta to use between values returned from today(). If not specified, it will increase by 1 with each call to today().
• delta_type – The type of the delta to use between values returned from today(). This can be any keyword parameter accepted by the timedelta constructor.
• strict – If True, calling the mock class and any of its methods will result in an instance of the mock being returned. If False, the default, an instance of date will be returned instead.

The mock returned will behave exactly as the datetime.date class with the exception of the following members:

tdate.add(*args, **kw)

This will add the datetime.date created from the supplied parameters to the queue of dates to be returned by today(). An instance of date may also be passed as a single positional argument.

tdate.set(*args, **kw)

This will set the datetime.date created from the supplied parameters as the next date to be returned by today(), regardless of any dates in the queue. An instance of date may also be passed as a single positional argument.

classmethod tdate.today()

This will return the next supplied or calculated date from the internal queue, rather than the actual current date.

testfixtures.test_datetime(year=2001, month=1, day=1, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, delta=None, delta_type='seconds', date_type=datetime.date, strict=False)

A function that returns a mock object that can be used in place of the datetime.datetime class but where the return value of now() can be controlled.

If a single positional argument of None is passed, then the queue of datetimes to be returned will be empty and you will need to call set() or add() before calling now() or utcnow().

Parameters:

• year – An optional year used to create the first datetime returned by now().
• month – An optional month used to create the first datetime returned by now().
• day – An optional day used to create the first datetime returned by now().
• hour – An optional hour used to create the first datetime returned by now().
• minute – An optional minute used to create the first datetime returned by now().
• second – An optional second used to create the first datetime returned by now().
• microsecond – An optional microsecond used to create the first datetime returned by now().
• tzinfo – An optional tzinfo that will be used to indicate the timezone intended for the values returned by returned by now(). It will be used to correctly calculate return values when tz is passed to now() and when utcnow() is called.
• delta – The size of the delta to use between values returned from now(). If not specified, it will increase by 1 with each call to now().
• delta_type – The type of the delta to use between values returned from now(). This can be any keyword parameter accepted by the timedelta constructor.
• date_type – The type to use for the return value of the date() method. This can help with gotchas that occur when type checking if performed on values returned by the mock’s date() method.
• strict – If True, calling the mock class and any of its methods will result in an instance of the mock being returned. If False, the default, an instance of datetime will be returned instead.

The mock returned will behave exactly as the datetime.datetime class with the exception of the following members:

tdatetime.add(*args, **kw)

This will add the datetime.datetime created from the supplied parameters to the queue of datetimes to be returned by now() or utcnow(). An instance of datetime may also be passed as a single positional argument.

tdatetime.set(*args, *kw)

This will set the datetime.datetime created from the supplied parameters as the next datetime to be returned by now() or utcnow(), clearing out any datetimes in the queue. An instance of datetime may also be passed as a single positional argument.

classmethod tdatetime.now([tz])

Parameters:tz – An optional timezone to apply to the returned time. If supplied, it must be an instance of a tzinfo subclass.

This will return the next supplied or calculated datetime from the internal queue, rather than the actual current datetime.

If tz is supplied, it will be applied to the datetime that would have have been returned from the internal queue, treating that datetime as if it were in the UTC timezone.

classmethod tdatetime.utcnow()

This will return the next supplied or calculated datetime from the internal queue, rather than the actual current UTC datetime.

No timezone will be applied, even that supplied to the constructor.

classmethod tdatetime.date()

This will return the date component of the current mock instance, but using the date type supplied when the mock class was created.

testfixtures.test_time(year=2001, month=1, day=1, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, delta=None, delta_type='seconds')

A function that returns a mock object that can be used in place of the time.time function but where the return value can be controlled.

If a single positional argument of None is passed, then the queue of times to be returned will be empty and you will need to call set() or add() before calling the mock.

Parameters:

• year – An optional year used to create the first time returned.
• month – An optional month used to create the first time.
• day – An optional day used to create the first time.
• hour – An optional hour used to create the first time.
• minute – An optional minute used to create the first time.
• second – An optional second used to create the first time.
• microsecond – An optional microsecond used to create the first time.
• delta – The size of the delta to use between values returned. If not specified, it will increase by 1 with each call to the mock.
• delta_type – The type of the delta to use between values returned. This can be any keyword parameter accepted by the timedelta constructor.

The mock additionally has the following methods available on it:

ttime.add(*args, **kw)

This will add the time specified by the supplied parameters to the queue of times to be returned by calls to the mock. The parameters are the same as the datetime.datetime constructor. An instance of datetime may also be passed as a single positional argument.

ttime.set(*args, **kw)

This will set the time specified by the supplied parameters as the next time to be returned by a call to the mock, regardless of any times in the queue. The parameters are the same as the datetime.datetime constructor. An instance of datetime may also be passed as a single positional argument.

testfixtures.wrap(before, after=None)

A decorator that causes the supplied callables to be called before or after the wrapped callable, as appropriate.

class testfixtures.components.TestComponents

A helper for providing a sterile registry when testing with zope.component.

Instantiation will install an empty registry that will be returned by zope.component.getSiteManager().

uninstall()

Remove the sterile registry and replace it with the one that was in place before this TestComponents was instantiated.

class testfixtures.manuel.Files(name)

A Manuel plugin that parses certain ReST sections to read and write files in the configured TempDirectory.

Parameters:name – This is the name of the TempDirectory to use in the Manual global namespace (ie: globs).

testfixtures.identity

A singleton used to identify comparisons of objects that are found to be identical.

testfixtures.not_there

A singleton used to represent the absence of a particular attribute.