testing.txt 6.27 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
Testing Support
===============

The zc.buildout.testing module provides an API that can be used when
writing recipe tests.  This API is documented below.  Many examples of
using this API can be found in the zc.buildout, zc.recipe.egg, and
zc.recipe.testrunner tests.

zc.buildout.testing.buildoutSetUp(test)
---------------------------------------

The buildoutSetup function can be used as a doctest setup function.
13 14 15
It creates a sample buildout that can be used by tests, changing the
current working directory to the sample_buildout. It also adds a
number of names to the test namespace:
16

Jim Fulton's avatar
Jim Fulton committed
17
``sample_buildout``
18 19
    This is the name of a buildout with a basic configuration.

20 21 22
``buildout``
    This is the path of the buildout script in the sample buildout.

Jim Fulton's avatar
Jim Fulton committed
23
``ls(*path)``
24 25 26
    List the contents of a directory.  The directory path is provided as one or
    more strings, to be joined with os.path.join.

Jim Fulton's avatar
Jim Fulton committed
27
``cat(*path)``
28 29 30 31 32 33 34
    Display the contents of a file.   The file path is provided as one or
    more strings, to be joined with os.path.join.

    On Windows, if the file doesn't exist, the function will try
    adding a '-script.py' suffix.  This helps to work around a
    difference in script generation on windows.

Jim Fulton's avatar
Jim Fulton committed
35
``mkdir(*path)``
36 37 38
    Create a directory. The directory path is provided as one or
    more strings, to be joined with os.path.join.

Jim Fulton's avatar
Jim Fulton committed
39
``rmdir(*path)``
40 41 42
    Remove a directory. The directory path is provided as one or
    more strings, to be joined with os.path.join.

Jim Fulton's avatar
Jim Fulton committed
43 44 45 46
``remove(*path)``
    Remove a directory or file. The path is provided as one or
    more strings, to be joined with os.path.join.

Jim Fulton's avatar
Jim Fulton committed
47
``tmpdir(name)``
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
    Create a temporary directory with the given name.  The directory
    will be automatically removed at the end of the test.  The path of
    the created directory is returned.

    Further, if the the normalize_path normlaizing substitution (see
    below) is used, then any paths starting with this path will be
    normalized to::

      /name/restofpath

    No two temporary directories can be created with the same name.  A
    directory created with tmpdir can be removed with rmdir and recreated.

    Note that the sample_buildout directory is created by calling this
    function.

Jim Fulton's avatar
Jim Fulton committed
64
``write(*path_and_contents)``
65 66 67
    Create a file.  The file path is provided as one or more strings,
    to be joined with os.path.join. The last argument is the file contents.

Jim Fulton's avatar
Jim Fulton committed
68
``system(command, input='')``
69 70 71 72
    Execute a system command with the given input passed to the
    command's standard input.  The output (error and regular output)
    from the command is returned.

Jim Fulton's avatar
Jim Fulton committed
73
``get(url)``
74 75
    Get a web page.

Jim Fulton's avatar
Jim Fulton committed
76
``cd(*path)``
77 78 79 80 81
    Change to the given directory.  The directory path is provided as one or
    more strings, to be joined with os.path.join.

    The directory will be reset at the end of the test.

Jim Fulton's avatar
Jim Fulton committed
82
``join(*path)``
83 84
    A convenient reference to os.path.join.

Jim Fulton's avatar
Jim Fulton committed
85
``register_teardown(func)``
86 87 88
    Register a tear-down function.  The function will be called with
    no arguments at the end of the test.

Jim Fulton's avatar
Jim Fulton committed
89
``start_server(path)``
90 91 92
    Start a web server on the given path.  The server will be shut
    down at the end of the test.  The server URL is returned.

Jim Fulton's avatar
Jim Fulton committed
93 94 95 96 97 98 99 100 101 102 103 104 105
    You can cause the server to start and stop logging it's output
    using: 

       >>> get(server_url+'enable_server_logging')

    and:

       >>> get(server_url+'enable_server_logging')

    This can be useful to see how buildout is interacting with a
    server.


Jim Fulton's avatar
Jim Fulton committed
106
``sdist(setup, dest)``
107 108 109 110 111
    Create a source distribution by running the given setup file and
    placing the result in the given destination directory.  If the
    setup argument is a directory, the thge setup.py file in that
    directory is used.

Jim Fulton's avatar
Jim Fulton committed
112
``bdist_egg(setup, executable, dest)``
113 114
    Create an egg by running the given setup file with the given
    Python executable and placing the result in the given destination
Jim Fulton's avatar
Jim Fulton committed
115
    directory.  If the setup argument is a directory, then the
116 117
    setup.py file in that directory is used.

Jim Fulton's avatar
Jim Fulton committed
118
``find_python(version)``
119 120 121 122 123 124 125 126 127 128 129 130 131
    Find a Python executable for the given version, where version is a
    string like "2.4".

    This function uses the following strategy to find a Python of the
    given version:

    - Look for an environment variable of the form PYTHON%(version)s.

    - On windows, look for \Pythonm%(version)s\python

    - on Unix, try running python%(version)s or just python to get the
      executable

Jim Fulton's avatar
Jim Fulton committed
132 133
``zc.buildout.testing.buildoutTearDown(test)``
----------------------------------------------
134 135 136 137

Tear down everything set up by zc.buildout.testing.buildoutSetUp.  Any
functions passed to register_teardown are called as well.

Jim Fulton's avatar
Jim Fulton committed
138 139
``install(project, destination)``
---------------------------------
140 141 142 143 144 145 146 147 148

Install eggs for a given project into a destination.  If the
destination is a test object, then the eggs directory of the
sample buildout (sample_buildout) defined by the test will be used.
Tests will use this to install the distributions for the packages
being tested (and their dependencies) into a sample buildout. The egg
to be used should already be loaded, by importing one of the modules
provided, before calling this function.

Jim Fulton's avatar
Jim Fulton committed
149 150
``install_develop(project, destination)``
-----------------------------------------
151 152 153 154

Like install, but a develop egg is installed even if the current egg
if not a develop egg.

Jim Fulton's avatar
Jim Fulton committed
155 156
``Output normalization``
------------------------
157 158 159 160 161 162 163 164 165 166 167

Recipe tests often generate output that is dependent on temporary file
locations, operating system conventions or Python versions.  To deal
with these dependencies, we often use
zope.testing.renormalizing.RENormalizing to normalize test output.
zope.testing.renormalizing.RENormalizing takes pairs of regular
expressions and substitutions. The zc.buildout.testing module provides
a few helpful variables that define regular-expression/substitution
pairs that you can pass to zope.testing.renormalizing.RENormalizing.


Jim Fulton's avatar
Jim Fulton committed
168
``normalize_path``
169 170 171
   Converts tests paths, based on directories created with tmpdir(),
   to simple paths.

Jim Fulton's avatar
Jim Fulton committed
172
``normalize_script``
173 174 175 176 177 178
   On Unix-like systems, scripts are implemented in single files
   without suffixes.  On windows, scripts are implemented with 2
   files, a -script.py file and a .exe file.  This normalization
   converts directory listings of Windows scripts to the form
   generated on UNix-like systems.

Jim Fulton's avatar
Jim Fulton committed
179
``normalize_egg_py``
180 181
   Normalize Python version and platform indicators, if specified, in
   egg names.