inputgen 0.7.1
Tool for automated input generation, useful for bounded exhaustive testing and the generation of complex data structures for test inputs.
License: MIT

============
``inputgen``
============


About
=====

``inputgen`` is a Python package that provides automated input generation,
useful for bounded exhaustive testing and the generation of complex data
structures for test inputs.

This tool was originally created as a class project |---| Verification and
Validation of Software with professor `Sarfraz Khurshid`_ |---| and is largely
modeled after Korat_ and its `related research`_.  Korat is an input generation
tool for Java programs.

Official documentation, other than this readme, is currently lacking; however,
the associated `class paper`_ provides a detailed description the
implementation and related research.

.. _Sarfraz Khurshid: http://users.ece.utexas.edu/~khurshid/
.. _Korat: http://korat.sourceforge.net/
.. _related research: http://korat.sourceforge.net/publications.html
.. _class paper: https://bitbucket.org/gdub/python-inputgen/raw/default/docs/paper.pdf


Features
========
* Uses multiple processes to speed input generation.
* Search space pruning:

  * *Backtracking* - The generated objects are instrumented to record the order
    of their field accesses, which occurs while checking the well-formedness of
    their structure in the defined predicate.  Upon rejection of an input
    combination, alternative values are first tried on the last-accessed
    field(s).

    This feature is enabled by default, and can be disabled by setting
    ``enable_backtracking=False`` when instantiating a ``Factory`` object.

  * *Non-isomorphic generation* - Only objects with unique structure are
    generated.  Two inputs are isomorphic_, or identical in structure, if their
    object graphs reachable from the root object are isomorphic.

    For example, if building a binary tree of size two, using five possible
    node objects, then there are only two possible valid, non-isomorphic
    structures |---| a root node and left child, or a root node and right
    child.

    This feature is enabled by default, and can be disabled by setting
    ``enable_iso_breaking=False`` when instantiating a ``Factory`` object.

.. _isomorphic: http://en.wikipedia.org/wiki/Isomorphism


Requirements and Installation
=============================

``inputgen`` requires Python 2.5 or later.  If using Python 2.6, ``inputgen``
will install and make use of the `stand-alone ordereddict`_ package.  If using
Python 2.5, ``inputgen`` will additionally install and make use of the
`stand-alone multiprocessing`_ package.

To install ``inputgen`` and required dependencies, run::

    pip install inputgen

The source can be found here: https://bitbucket.org/gdub/python-inputgen/


.. _stand-alone ordereddict: http://pypi.python.org/pypi/ordereddict/
.. _stand-alone multiprocessing: http://pypi.python.org/pypi/multiprocessing/


Example
=======

Below is a simple example.  For more examples, see the ``inputgen/examples/``
directory.

Given the following code::

    import inputgen

    class SquareTest(inputgen.TestCase):

        @staticmethod
        def repOK(factory):
            return True

        @staticmethod
        def fin(min=0, max=10):
            f = inputgen.Factory(enable_backtracking=False,
                                 enable_iso_breaking=False)
            f.set('number', range(min, max))
            return f

        def run_method(self, factory):
            num = factory.number
            self.assertEqual(num * num, num ** 2)

    if __name__ == "__main__":
        import unittest
        unittest.main()

Save the code to a file named ``square.py`` and then run the unit test::

    python square.py

When run, ``inputgen`` will generate all possible combinations of the
finitized fields.  In the example above this will produce ten combinations,
with a single field (``number``) ranging from 0 to 9.


.. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
   :trim: