source: TI12-security/trunk/NDGSecurity/python/buildout/ndgsecurity/eggs/zc.buildout-1.2.1-py2.5.egg/zc/buildout/testing.txt @ 7081

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg-security/TI12-security/trunk/NDGSecurity/python/buildout/ndgsecurity/eggs/zc.buildout-1.2.1-py2.5.egg/zc/buildout/testing.txt@7081
Revision 7081, 6.3 KB checked in by pjkersha, 11 years ago (diff)
  • Property svn:keywords set to Id
Line 
1Testing Support
2===============
3
4The zc.buildout.testing module provides an API that can be used when
5writing recipe tests.  This API is documented below.  Many examples of
6using this API can be found in the zc.buildout, zc.recipe.egg, and
7zc.recipe.testrunner tests.
8
9zc.buildout.testing.buildoutSetUp(test)
10---------------------------------------
11
12The buildoutSetup function can be used as a doctest setup function.
13It creates a sample buildout that can be used by tests, changing the
14current working directory to the sample_buildout. It also adds a
15number of names to the test namespace:
16
17``sample_buildout``
18    This is the name of a buildout with a basic configuration.
19
20``buildout``
21    This is the path of the buildout script in the sample buildout.
22
23``ls(*path)``
24    List the contents of a directory.  The directory path is provided as one or
25    more strings, to be joined with os.path.join.
26
27``cat(*path)``
28    Display the contents of a file.   The file path is provided as one or
29    more strings, to be joined with os.path.join.
30
31    On Windows, if the file doesn't exist, the function will try
32    adding a '-script.py' suffix.  This helps to work around a
33    difference in script generation on windows.
34
35``mkdir(*path)``
36    Create a directory. The directory path is provided as one or
37    more strings, to be joined with os.path.join.
38
39``rmdir(*path)``
40    Remove a directory. The directory path is provided as one or
41    more strings, to be joined with os.path.join.
42
43``remove(*path)``
44    Remove a directory or file. The path is provided as one or
45    more strings, to be joined with os.path.join.
46
47``tmpdir(name)``
48    Create a temporary directory with the given name.  The directory
49    will be automatically removed at the end of the test.  The path of
50    the created directory is returned.
51
52    Further, if the the normalize_path normlaizing substitution (see
53    below) is used, then any paths starting with this path will be
54    normalized to::
55
56      /name/restofpath
57
58    No two temporary directories can be created with the same name.  A
59    directory created with tmpdir can be removed with rmdir and recreated.
60
61    Note that the sample_buildout directory is created by calling this
62    function.
63
64``write(*path_and_contents)``
65    Create a file.  The file path is provided as one or more strings,
66    to be joined with os.path.join. The last argument is the file contents.
67
68``system(command, input='')``
69    Execute a system command with the given input passed to the
70    command's standard input.  The output (error and regular output)
71    from the command is returned.
72
73``get(url)``
74    Get a web page.
75
76``cd(*path)``
77    Change to the given directory.  The directory path is provided as one or
78    more strings, to be joined with os.path.join.
79
80    The directory will be reset at the end of the test.
81
82``join(*path)``
83    A convenient reference to os.path.join.
84
85``register_teardown(func)``
86    Register a tear-down function.  The function will be called with
87    no arguments at the end of the test.
88
89``start_server(path)``
90    Start a web server on the given path.  The server will be shut
91    down at the end of the test.  The server URL is returned.
92
93    You can cause the server to start and stop logging it's output
94    using:
95
96       >>> get(server_url+'enable_server_logging')
97
98    and:
99
100       >>> get(server_url+'disable_server_logging')
101
102    This can be useful to see how buildout is interacting with a
103    server.
104
105
106``sdist(setup, dest)``
107    Create a source distribution by running the given setup file and
108    placing the result in the given destination directory.  If the
109    setup argument is a directory, the thge setup.py file in that
110    directory is used.
111
112``bdist_egg(setup, executable, dest)``
113    Create an egg by running the given setup file with the given
114    Python executable and placing the result in the given destination
115    directory.  If the setup argument is a directory, then the
116    setup.py file in that directory is used.
117
118``find_python(version)``
119    Find a Python executable for the given version, where version is a
120    string like "2.4".
121
122    This function uses the following strategy to find a Python of the
123    given version:
124
125    - Look for an environment variable of the form PYTHON%(version)s.
126
127    - On windows, look for \Pythonm%(version)s\python
128
129    - on Unix, try running python%(version)s or just python to get the
130      executable
131
132``zc.buildout.testing.buildoutTearDown(test)``
133----------------------------------------------
134
135Tear down everything set up by zc.buildout.testing.buildoutSetUp.  Any
136functions passed to register_teardown are called as well.
137
138``install(project, destination)``
139---------------------------------
140
141Install eggs for a given project into a destination.  If the
142destination is a test object, then the eggs directory of the
143sample buildout (sample_buildout) defined by the test will be used.
144Tests will use this to install the distributions for the packages
145being tested (and their dependencies) into a sample buildout. The egg
146to be used should already be loaded, by importing one of the modules
147provided, before calling this function.
148
149``install_develop(project, destination)``
150-----------------------------------------
151
152Like install, but a develop egg is installed even if the current egg
153if not a develop egg.
154
155``Output normalization``
156------------------------
157
158Recipe tests often generate output that is dependent on temporary file
159locations, operating system conventions or Python versions.  To deal
160with these dependencies, we often use
161zope.testing.renormalizing.RENormalizing to normalize test output.
162zope.testing.renormalizing.RENormalizing takes pairs of regular
163expressions and substitutions. The zc.buildout.testing module provides
164a few helpful variables that define regular-expression/substitution
165pairs that you can pass to zope.testing.renormalizing.RENormalizing.
166
167
168``normalize_path``
169   Converts tests paths, based on directories created with tmpdir(),
170   to simple paths.
171
172``normalize_script``
173   On Unix-like systems, scripts are implemented in single files
174   without suffixes.  On windows, scripts are implemented with 2
175   files, a -script.py file and a .exe file.  This normalization
176   converts directory listings of Windows scripts to the form
177   generated on UNix-like systems.
178
179``normalize_egg_py``
180   Normalize Python version and platform indicators, if specified, in
181   egg names.
Note: See TracBrowser for help on using the repository browser.