README

   1 Gajja: Fake objects for real tests
   2 ##################################
   3
   4 The `gajja` library provides a system of Python `test double`_ classes
   5 for specific system objects:
   6
   7 * `Filesystem entries`_
   8
   9 * `Subprocesses`_
  10
  11 ..  _test double: http://xunitpatterns.com/Test%20Double.html
  12
  13 The Korean word 가짜 (*gajja*; IPA ˈkaːt͡ɕ̤a) means “fake thing”.
  14
  15
  16 ============
  17 Test doubles
  18 ============
  19
  20 Filesystem entries
  21 ==================
  22
  23 * Create a `gajja.FileDouble` instance for the specific filesystem
  24   path, and the file content you want the fake file to present.
  25
  26 * Register that `FileDouble` instance to the test case, so it will
  27   only be faked during that one test case.
  28
  29 * Call helper functions that wrap a `mock.patch` object around each of
  30   the specific system APIs that access the filesystem (e.g.
  31   `gajja.patch_os_path_exists`, `gajja.patch_os_stat`, etc.).
  32
  33 * Customise the `FileDouble` instance's behaviour in response to any
  34   of those interfaces (e.g. `FileDouble.set_os_stat_scenario`, etc.),
  35   or leave the default behaviour.
  36
  37 * Test your program code as normal, letting it call the filesystem
  38   access APIs. When the program accesses the filesystem path for the
  39   `FileDouble`, the test double's behaviour will be invoked; for any
  40   other filesystem path, the normal API's behaviour will occur.
  41
  42 * Inspect the `FileDouble` instance for changes you need to assert in
  43   the unit test (e.g. `FileDouble.fake_file.getvalue`). Inspect the
  44   API mock objects to see how they were called (e.g.
  45   `os.stat.assert_called_with`).
  46
  47 * At the end of the test case, `mock.patch` will ensure the wrapper is
  48   removed and the normal API behaviour continues.
  49
  50
  51 Subprocesses
  52 ============
  53
  54
  55 \f
  56 =======
  57 Copying
  58 =======
  59
  60 Copyright © 2015–2016 Ben Finney <ben+python@benfinney.id.au>
  61
  62 This is free software: you may copy, modify, and/or distribute this work
  63 under the terms of the GNU General Public License as published by the
  64 Free Software Foundation; version 3 of that license or any later version.
  65 No warranty expressed or implied. See the file ‘LICENSE.GPL-3’ for details.
  66
  67 \f
  68 ..
  69     This document is written using `reStructuredText`_ markup, and can
  70     be rendered with `Docutils`_ to other formats.
  71
  72     ..  _Docutils: http://docutils.sourceforge.net/
  73     ..  _reStructuredText: http://docutils.sourceforge.net/rst.html
  74
  75 ..
  76     Local variables:
  77     coding: utf-8
  78     mode: text
  79     mode: rst
  80     End:
  81     vim: fileencoding=utf-8 filetype=rst :