python-gajja/README

Gajja: Fake objects for real tests
##################################

The `gajja` library provides a system of Python `test double`_ classes
for specific system objects:

* `Filesystem entries`_

* `Subprocesses`_

..  _test double: http://xunitpatterns.com/Test%20Double.html

The Korean word 가짜 (*gajja*; IPA ˈkaːt͡ɕ̤a) means “fake thing”.


============
Test doubles
============

Filesystem entries
==================

* Create a `gajja.FileDouble` instance for the specific filesystem
  path, and the file content you want the fake file to present.

* Register that `FileDouble` instance to the test case, so it will
  only be faked during that one test case.

* Call helper functions that wrap a `mock.patch` object around each of
  the specific system APIs that access the filesystem (e.g.
  `gajja.patch_os_path_exists`, `gajja.patch_os_stat`, etc.).

* Customise the `FileDouble` instance's behaviour in response to any
  of those interfaces (e.g. `FileDouble.set_os_stat_scenario`, etc.),
  or leave the default behaviour.

* Test your program code as normal, letting it call the filesystem
  access APIs. When the program accesses the filesystem path for the
  `FileDouble`, the test double's behaviour will be invoked; for any
  other filesystem path, the normal API's behaviour will occur.

* Inspect the `FileDouble` instance for changes you need to assert in
  the unit test (e.g. `FileDouble.fake_file.getvalue`). Inspect the
  API mock objects to see how they were called (e.g.
  `os.stat.assert_called_with`).

* At the end of the test case, `mock.patch` will ensure the wrapper is
  removed and the normal API behaviour continues.


Subprocesses
============



=======
Copying
=======

Copyright © 2015–2016 Ben Finney <ben+python@benfinney.id.au>

This is free software: you may copy, modify, and/or distribute this work
under the terms of the GNU General Public License as published by the
Free Software Foundation; version 3 of that license or any later version.
No warranty expressed or implied. See the file ‘LICENSE.GPL-3’ for details.


..
    This document is written using `reStructuredText`_ markup, and can
    be rendered with `Docutils`_ to other formats.

    ..  _Docutils: http://docutils.sourceforge.net/
    ..  _reStructuredText: http://docutils.sourceforge.net/rst.html

..
    Local variables:
    coding: utf-8
    mode: text
    mode: rst
    End:
    vim: fileencoding=utf-8 filetype=rst :