Testing with files and directories
==================================

.. currentmodule:: testfixtures

Working with files and directories in tests can often require
excessive amounts of boilerplate code to make sure that the tests
happen in their own sandbox, files and directories contain what they
should or code processes test files correctly, and the sandbox is
cleared up at the end of the tests.

Methods of use
--------------
To help with this, TestFixtures provides the
:class:`TempDirectory` class that hides most of the
boilerplate code you would need to write.

Suppose you wanted to test the following function:

.. code-block:: python

  import os

  def foo2bar(dirpath,filename):
    path = os.path.join(dirpath,filename)
    with open(path) as input:
        data = input.read()
    data = data.replace('foo','bar')
    with open(path,'w') as output:
        output.write(data)

There are several different ways depending on the type of test you are
writing:

The context manager
~~~~~~~~~~~~~~~~~~~

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

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


The decorator
~~~~~~~~~~~~~

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

.. code-block:: python

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

.. check the above raises no assertion error:

  >>> test_function()

Manual usage
~~~~~~~~~~~~

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

The instantiation and replacement are done in the ``setUp`` function
of the :class:`~unittest.TestCase` or passed to the
:class:`~doctest.DocTestSuite` constructor:

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

You can then use the temporary directory for your testing:

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

Then, in the ``tearDown`` function
of the :class:`~unittest.TestCase` or passed to the
:class:`~doctest.DocTestSuite` constructor, you should make sure the
temporary directory is cleaned up:

>>> d.cleanup()

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

>>> TempDirectory.cleanup_all()

Features of a temporary directory
---------------------------------

No matter which usage pattern you pick, you will always end up with a
:class:`TempDirectory` object. These have an array of
methods that let you perform common file and directory related tasks
without all the manual boiler plate. The following sections show you
how to perform the various tasks you're likely to bump into in the
course of testing.

.. create a tempdir for the examples:

  >>> tempdir = TempDirectory()

Computing paths
~~~~~~~~~~~~~~~

If you need to know the real path of the temporary directory, the
:class:`TempDirectory` object has a :attr:`~TempDirectory.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
:meth:`~TempDirectory.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']

.. note:: 

  If passing a string containing path separators, a forward
  slash should be used as the separator regardless of the underlying
  platform separator.

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','some text')
'...'
>>> with file(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','some more text')
>>> with file(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'),'the text')
>>> with file(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','the text')
>>> with file(path) as f:
...     print f.read()
the text

Forward slashes should be used regardless of the file system or operating system
in use.

Creating directories
~~~~~~~~~~~~~~~~~~~~

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

.. new tempdir:

  >>> tempdir = TempDirectory()

>>> 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
>>> tempdir.makedir('another/sub/dir')
'...'
>>> os.path.exists(path)
True

Forward slashes should be used regardless of the file system or operating system
in use.

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
:meth:`TempDirectory.read` method.

Suppose the code you are testing creates some files:

.. new tempdir:

  >>> tempdir = TempDirectory()

.. code-block:: python

 def spew(path):
    with file(os.path.join(path,'root.txt'),'w') as f:
        f.write('root output')
    os.mkdir(os.path.join(path,'subdir'))
    with file(os.path.join(path,'subdir','file.txt'),'w') as f:
        f.write('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 :meth:`TempDirectory.read` method to
check the files were created with the correct content:

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

The second part of the above test shows how to use the
:meth:`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')
'subdir output'

Forward slashes should be used regardless of the file system or operating system
in use.

Checking the contents of directories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:class:`TempDirectory` objects have several methods
for checking the names of files and directories they contain, which
one you use depends on whether you're unit testing or testing
docuemntation. In  all cases, the methods provided sort the list of
actual files alphanumerically so that the ordering will always remain
constant.

As an example, to check that the :func:`spew` function above created no
extraneous files, we could use the
:meth:`~testfixtures.TempDirectory.listdir` method as follows:

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

This 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
:meth:`~testfixtures.TempDirectory.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 :func:`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 :meth:`~testfixtures.TempDirectory.listdir`:

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

For unit tests, three methods are providing for checking the contents of
a temporary directory. 

The :meth:`~testfixtures.TempDirectory.check` method is called with
the expected contents of the temporary directory:

>>> tempdir.check('root.txt','subdir')

It returns no output if the directory contents match the expected
contents passed in, but if they do not, an
:class:`~exceptions.AssertionError` is raised, which will show up as a
unit test failure:

>>> tempdir.check('subdir')
Traceback (most recent call last):
...
AssertionError: Sequence not as expected:
<BLANKLINE>
same:
()
<BLANKLINE>
first:
('subdir',)
<BLANKLINE>
second:
('root.txt', 'subdir')

To check the contents of a sub-directory of the temporary directory,
the :meth:`~testfixtures.TempDirectory.check_dir` method is used in a
similar fashion:

>>> tempdir.check_dir('subdir','file.txt','logs')

Both the :meth:`~testfixtures.TempDirectory.check` and
:meth:`~testfixtures.TempDirectory.check_dir` methods can be used to
check whether a directory contains nothing, for example:

>>> tempdir.check_dir(('subdir','logs'))

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

>>> tempdir.check_dir('subdir/logs')

You may also want to recursively check the contents of a whole subtree
of the temporary directory. This can be done with the
:meth:`~testfixtures.TempDirectory.check_all` method:

>>> tempdir.check_all('subdir','file.txt','logs/')

This method can also be used to check the contents of the entire
temporary directory by passing an empty string as the first parameter:

>>> tempdir.check_all('',
...     'root.txt',
...     'subdir/',
...     'subdir/file.txt',
...     'subdir/logs/')

In some circumstances, you may want to ignore certain files or
sub-directories when checking contents. To make this easy, the
:class:`~testfixtures.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 revison control system's metadata
directories, which may or may not be present:

.. code-block:: python
 
  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),'w') as f:
      f.write('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.listdir()
test.txt

The decorator would be as follows:

.. code-block:: python

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

.. check the above raises no assertion error:

  >>> test_function()

Working with an existing sandbox
--------------------------------

Some testing infrastructure already provides a sandbox temporary
directory, however that infrastructure might not provide the same
level of functionality that :class:`~testfixtures.TempDirectory`
provides.

For this reason, it is possible to wrap an existing directory such as
the following with a :class:`~testfixtures.TempDirectory`:

>>> from tempfile import mkdtemp
>>> thedir = mkdtemp()

When working with the context manager, this is done as follows:

>>> with TempDirectory(path=thedir) as d:
...   d.write('file','data')
...   d.makedir('directory')
...   sorted(os.listdir(thedir))
'...'
'...'
['directory', 'file']

.. check thedir still exists and reset

  >>> from shutil import rmtree
  >>> os.path.exists(thedir)
  True
  >>> rmtree(thedir)
  >>> thedir = mkdtemp()

For the decorator, usage would be as follows:

.. code-block:: python

  from testfixtures import tempdir,compare
  
  @tempdir(path=thedir)
  def test_function(d):
      d.write('file','data')
      d.makedir('directory')
      assert sorted(os.listdir(thedir))==['directory','file']

.. check the above raises no assertion error and that thedir still
   exits:

  >>> test_function()
  >>> os.path.exists(thedir)
  True

It is important to note that if an existing directory is used, it will
not be deleted by either the decorator or the context manager. You
will need to make sure that the directory is cleaned up as required.

.. check the above statement is true:

  >>> os.path.exists(thedir)
  True

.. better clean it up:

 >>> rmtree(thedir)

Using with Manuel
-----------------

`Manuel`__ is an excellent take on testing the examples found in
documentation. It works by applying a set of specialised
parsers to the documentation and testing or otherwise using the the
blocks returned by those parsers.

__ http://pypi.python.org/pypi/manuel

The key differences between testing with Manuel and the traditional
doctest are that it is possible to plug in different types of parser,
not just the "python console session" one, and so it is possible to
test different types of examples. TestFixtures provides one these
plugins to aid working with 
:class:`~testfixtures.TempDirectory` objects. This plugin makes use of
:rst:dir:`topic` directives with specific classes set to perform
different actions. 

The following sections describe how to use this plugin to help with
writing temporary files and checking their contents.

Setting up
~~~~~~~~~~

To use the Manuel plugin, you need to make sure a
:class:`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
:class:`~manuel.testing.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: 

.. literalinclude:: ../testfixtures/tests/test_manuel_examples.py
   :lines: 7-

Writing files
~~~~~~~~~~~~~

To write a file with the plugin, a :rst:dir:`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:

.. literalinclude:: ../testfixtures/tests/configparser-read.txt

Checking the contents of files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To read a file with the plugin, a :rst:dir:`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:

.. literalinclude:: ../testfixtures/tests/configparser-write.txt

Checking the contents of directories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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

.. literalinclude:: ../testfixtures/tests/directory-contents.txt

.. clean up all tempdirs:

  >>> TempDirectory.cleanup_all()
