Metadata-Version: 1.0
Name: zc.recipe.testrunner
Version: 1.0.0b6
Summary: ZC Buildout recipe for creating test runners
Home-page: http://svn.zope.org/zc.buildout
Author: Jim Fulton
Author-email: jim@zope.com
License: ZPL 2.1
Description: ******************
        Test-Runner Recipe
        ******************
        
        .. contents::
        
        This recipe generates zope.testing test-runner scripts for testing a
        collection of eggs.  The eggs must already be installed (using the
        zc.recipe.egg recipe).
        
        
        Change History
        **************
        
        1.0.0b6 (2007-02-25)
        ====================
        
        Feature Changes
        ---------------
        
        - If the working directory is not specified, or specified as the empty
        string, an empty part directory is created for the tests to run in.
        
        1.0.0b5 (2007-01-24)
        ====================
        
        Bugs fixed
        ----------
        
        - When:
        
        + the working-directory option was used,
        + and the test runner needed to restart itself
        + and the test runner was run with a relative path (e.g. bin/test)
        
        then the testrunner could not restart itself successfully because the
        relative path in sys.argv[0] was no-longer valid.
        
        Now we convert sys.argv[0] to an absolute path.
        
        1.0.0b4 (2006-10-24)
        ====================
        
        Feature Changes
        ---------------
        
        - Added a working-directoy option to specify a working directory for
        the generated script.
        
        
        1.0.0b3 (2006-10-16)
        ====================
        
        Updated to work with (not get a warning from) zc.buildout 1.0.0b10.
        
        1.0.0b2
        =======
        
        Added a defaults option to specify testrunner default options.
        
        1.0.0b1
        =======
        
        Updated to work with zc.buildout 1.0.0b5.
        
        1.0.0a3
        =======
        
        Added a defaults option that lets you specify test-runner default
        options.
        
        
        1.0.0a2
        =======
        
        Now provide a extra-paths option for including extra paths in test
        scripts. This is useful when eggs depend on Python packages not
        packaged as eggs.
        
        
        1.0.0a1
        =======
        
        Initial public version
        
        Detailed Documentation
        **********************
        
        Test-Runner Recipe
        ==================
        
        The test-runner recipe, zc.recipe.testrunner, creates a test runner
        for a project.
        
        The test-runner recipe has several options:
        
        eggs
        The eggs option specified a list of eggs to test given as one ore
        more setuptools requirement strings.  Each string must be given on
        a separate line.
        
        script
        The script option gives the name of the script to generate, in the
        buildout bin directory.  Of the option isn't used, the part name
        will be used.
        
        extra-paths
        One or more extra paths to include in the generated test script.
        
        defaults
        The defaults option lets you specify testrunner default
        options. These are specified as Python source for an expression
        yielding a list, typically a list literal.
        
        working-directory
        The working-directory option lets to specify a directory where the
        tests will run. The testrunner will change to this directory when
        run. If the working directory is the empty string or not specified
        at all, the recipe will create a working directory among the parts.
        
        (Note that, at this time, due to limitations in the Zope test runner,
        the distributions cannot be zip files. TODO: Fix the test runner!)
        
        To illustrate this, we'll create a pair of projects in our sample
        buildout:
        
        >>> mkdir(sample_buildout, 'demo')
        >>> mkdir(sample_buildout, 'demo', 'demo')
        >>> write(sample_buildout, 'demo', 'demo', '__init__.py', '')
        >>> write(sample_buildout, 'demo', 'demo', 'tests.py',
        ... '''
        ... import unittest
        ...
        ... class TestDemo(unittest.TestCase):
        ...    def test(self):
        ...        pass
        ...
        ... def test_suite():
        ...     return unittest.makeSuite(TestDemo)
        ... ''')
        
        >>> write(sample_buildout, 'demo', 'setup.py',
        ... """
        ... from setuptools import setup
        ...
        ... setup(name = "demo")
        ... """)
        
        >>> write(sample_buildout, 'demo', 'README.txt', '')
        
        >>> mkdir(sample_buildout, 'demo2')
        >>> mkdir(sample_buildout, 'demo2', 'demo2')
        >>> write(sample_buildout, 'demo2', 'demo2', '__init__.py', '')
        >>> write(sample_buildout, 'demo2', 'demo2', 'tests.py',
        ... '''
        ... import unittest
        ...
        ... class Demo2Tests(unittest.TestCase):
        ...    def test2(self):
        ...        pass
        ...
        ... def test_suite():
        ...     return unittest.makeSuite(Demo2Tests)
        ... ''')
        
        >>> write(sample_buildout, 'demo2', 'setup.py',
        ... """
        ... from setuptools import setup
        ...
        ... setup(name = "demo2", install_requires= ['demoneeded'])
        ... """)
        
        >>> write(sample_buildout, 'demo2', 'README.txt', '')
        
        Demo 2 depends on demoneeded:
        
        >>> mkdir(sample_buildout, 'demoneeded')
        >>> mkdir(sample_buildout, 'demoneeded', 'demoneeded')
        >>> write(sample_buildout, 'demoneeded', 'demoneeded', '__init__.py', '')
        >>> write(sample_buildout, 'demoneeded', 'demoneeded', 'tests.py',
        ... '''
        ... import unittest
        ...
        ... class TestNeeded(unittest.TestCase):
        ...    def test_needed(self):
        ...        pass
        ...
        ... def test_suite():
        ...     return unittest.makeSuite(TestNeeded)
        ... ''')
        
        >>> write(sample_buildout, 'demoneeded', 'setup.py',
        ... """
        ... from setuptools import setup
        ...
        ... setup(name = "demoneeded")
        ... """)
        
        >>> write(sample_buildout, 'demoneeded', 'README.txt', '')
        
        We'll update our buildout to install the demo project as a
        develop egg and to create the test script:
        
        >>> write(sample_buildout, 'buildout.cfg',
        ... """
        ... [buildout]
        ... develop = demo demoneeded demo2
        ... parts = testdemo
        ... offline = true
        ...
        ... [testdemo]
        ... recipe = zc.recipe.testrunner
        ... eggs =
        ...    demo
        ...    demo2
        ... script = test
        ... """)
        
        Note that we specified both demo and demo2 in the eggs
        option and that we put them on separate lines.
        
        We also specified the offline option to run the buildout in offline mode.
        
        Now when we run the buildout:
        
        >>> import os
        >>> os.chdir(sample_buildout)
        >>> print system(os.path.join(sample_buildout, 'bin', 'buildout') + ' -q'),
        
        We get a test script installed in our bin directory:
        
        >>> ls(sample_buildout, 'bin')
        -  buildout
        -  test
        
        We also get a part directory for the tests to run in:
        
        >>> ls(sample_buildout, 'parts')
        d  testdemo
        
        And updating leaves its contents intact:
        
        >>> _ = system(os.path.join(sample_buildout, 'bin', 'test') +
        ...            ' -q --coverage=coverage')
        >>> ls(sample_buildout, 'parts', 'testdemo')
        d  coverage
        >>> print system(os.path.join(sample_buildout, 'bin', 'buildout') + ' -q'),
        >>> ls(sample_buildout, 'parts', 'testdemo')
        d  coverage
        
        We can run the test script to run our demo test:
        
        >>> print system(os.path.join(sample_buildout, 'bin', 'test') + ' -vv'),
        Running tests at level 1
        Running unit tests:
        Running:
        test (demo.tests.TestDemo)
        test2 (demo2.tests.Demo2Tests)
        Ran 2 tests with 0 failures and 0 errors in 0.000 seconds.
        
        Note that we didn't run the demoneeded tests.  Tests are only run for
        the eggs listed, not for their dependencies.
        
        If we leave the script option out of the configuration, then the test
        script will get it's name from the part:
        
        >>> write(sample_buildout, 'buildout.cfg',
        ... """
        ... [buildout]
        ... develop = demo
        ... parts = testdemo
        ... offline = true
        ...
        ... [testdemo]
        ... recipe = zc.recipe.testrunner
        ... eggs = demo
        ... """)
        
        >>> print system(os.path.join(sample_buildout, 'bin', 'buildout') + ' -q'),
        
        >>> ls(sample_buildout, 'bin')
        -  buildout
        -  testdemo
        
        We can run the test script to run our demo test:
        
        >>> print system(os.path.join(sample_buildout, 'bin', 'testdemo') + ' -q'),
        Running unit tests:
        Ran 1 tests with 0 failures and 0 errors in 0.000 seconds.
        
        If we need to include other paths in our test script, we can use the
        extra-paths option to specify them:
        
        >>> write(sample_buildout, 'buildout.cfg',
        ... """
        ... [buildout]
        ... develop = demo
        ... parts = testdemo
        ... offline = true
        ...
        ... [testdemo]
        ... recipe = zc.recipe.testrunner
        ... eggs = demo
        ... extra-paths = /usr/local/zope/lib/python
        ... """)
        
        >>> print system(os.path.join(sample_buildout, 'bin', 'buildout') + ' -q'),
        
        >>> cat(sample_buildout, 'bin', 'testdemo')
        #!/usr/local/bin/python2.4
        <BLANKLINE>
        import sys
        sys.path[0:0] = [
        '/sample-buildout/demo',
        '/sample-buildout/eggs/zope.testing-3.0-py2.3.egg',
        '/sample-buildout/eggs/setuptools-0.6-py1.3.egg',
        '/usr/local/zope/lib/python',
        ]
        <BLANKLINE>
        import os
        sys.argv[0] = os.path.abspath(sys.argv[0])
        os.chdir('/sample-buildout/parts/testdemo')
        <BLANKLINE>
        import zope.testing.testrunner
        <BLANKLINE>
        if __name__ == '__main__':
        zope.testing.testrunner.run([
        '--test-path', '/sample-buildout/demo',
        ])
        
        We can use the working-directory option to specify a working
        directory:
        
        >>> write(sample_buildout, 'buildout.cfg',
        ... """
        ... [buildout]
        ... develop = demo
        ... parts = testdemo
        ... offline = true
        ...
        ... [testdemo]
        ... recipe = zc.recipe.testrunner
        ... eggs = demo
        ... extra-paths = /usr/local/zope/lib/python
        ... working-directory = /foo/bar
        ... """)
        
        >>> print system(os.path.join(sample_buildout, 'bin', 'buildout') + ' -q'),
        
        >>> cat(sample_buildout, 'bin', 'testdemo')
        #!/usr/local/bin/python2.4
        <BLANKLINE>
        import sys
        sys.path[0:0] = [
        '/sample-buildout/demo',
        '/sample-buildout/eggs/zope.testing-3.0-py2.3.egg',
        '/sample-buildout/eggs/setuptools-0.6-py1.3.egg',
        '/usr/local/zope/lib/python',
        ]
        <BLANKLINE>
        import os
        sys.argv[0] = os.path.abspath(sys.argv[0])
        os.chdir('/foo/bar')
        <BLANKLINE>
        import zope.testing.testrunner
        <BLANKLINE>
        if __name__ == '__main__':
        zope.testing.testrunner.run([
        '--test-path', '/sample-buildout/demo',
        ])
        
        Now that out tests use a specified working directory, their designated
        part directory is gone:
        
        >>> ls(sample_buildout, 'parts')
        
        
        If we need to specify default options, we can use the defaults
        option. For example, Zope 3 applications typically define test suites
        in modules named ftests or tests.  The default test runner behaviour
        is to look in modules named tests.  To specify that we want to look in
        tests and ftests module, we'd supply a default for the --tests-pattern
        option.  If we like dots, we could also request more verbose output
        using the -v option.
        
        >>> write(sample_buildout, 'buildout.cfg',
        ... """
        ... [buildout]
        ... develop = demo
        ... parts = testdemo
        ... offline = true
        ...
        ... [testdemo]
        ... recipe = zc.recipe.testrunner
        ... eggs = demo
        ... extra-paths = /usr/local/zope/lib/python
        ... defaults = ['--tests-pattern', '^f?tests$',
        ...             '-v'
        ...            ]
        ... """)
        
        >>> print system(os.path.join(sample_buildout, 'bin', 'buildout') + ' -q'),
        
        >>> cat(sample_buildout, 'bin', 'testdemo')
        #!/usr/local/bin/python2.4
        <BLANKLINE>
        import sys
        sys.path[0:0] = [
        '/sample-buildout/demo',
        '/sample-buildout/eggs/zope.testing-3.0-py2.4.egg',
        '/sample-buildout/eggs/setuptools-0.6-py1.3.egg',
        '/usr/local/zope/lib/python',
        ]
        <BLANKLINE>
        import os
        sys.argv[0] = os.path.abspath(sys.argv[0])
        os.chdir('/sample-buildout/parts/testdemo')
        <BLANKLINE>
        import zope.testing.testrunner
        <BLANKLINE>
        if __name__ == '__main__':
        zope.testing.testrunner.run((['--tests-pattern', '^f?tests$',
        '-v'
        ]) + [
        '--test-path', '/sample-buildout/demo',
        ])
        
        Some things to note from this example:
        
        - Parentheses are placed around the given expression.
        
        - Leading whitespace is removed.
        
        
        
        Download
        **********************
        
Keywords: development build testing
Platform: UNKNOWN
Classifier: Framework :: Buildout
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
