--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/eggs/zc.buildout-1.5.2-py2.6.egg/zc/buildout/testing.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,181 @@
+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.
+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:
+
+``sample_buildout``
+ This is the name of a buildout with a basic configuration.
+
+``buildout``
+ This is the path of the buildout script in the sample buildout.
+
+``ls(*path)``
+ List the contents of a directory. The directory path is provided as one or
+ more strings, to be joined with os.path.join.
+
+``cat(*path)``
+ 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.
+
+``mkdir(*path)``
+ Create a directory. The directory path is provided as one or
+ more strings, to be joined with os.path.join.
+
+``rmdir(*path)``
+ Remove a directory. The directory path is provided as one or
+ more strings, to be joined with os.path.join.
+
+``remove(*path)``
+ Remove a directory or file. The path is provided as one or
+ more strings, to be joined with os.path.join.
+
+``tmpdir(name)``
+ 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.
+
+``write(*path_and_contents)``
+ 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.
+
+``system(command, input='')``
+ 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.
+
+``get(url)``
+ Get a web page.
+
+``cd(*path)``
+ 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.
+
+``join(*path)``
+ A convenient reference to os.path.join.
+
+``register_teardown(func)``
+ Register a tear-down function. The function will be called with
+ no arguments at the end of the test.
+
+``start_server(path)``
+ 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.
+
+ You can cause the server to start and stop logging it's output
+ using:
+
+ >>> get(server_url+'enable_server_logging')
+
+ and:
+
+ >>> get(server_url+'disable_server_logging')
+
+ This can be useful to see how buildout is interacting with a
+ server.
+
+
+``sdist(setup, dest)``
+ 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.
+
+``bdist_egg(setup, executable, dest)``
+ Create an egg by running the given setup file with the given
+ Python executable and placing the result in the given destination
+ directory. If the setup argument is a directory, then the
+ setup.py file in that directory is used.
+
+``find_python(version)``
+ 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
+
+``zc.buildout.testing.buildoutTearDown(test)``
+----------------------------------------------
+
+Tear down everything set up by zc.buildout.testing.buildoutSetUp. Any
+functions passed to register_teardown are called as well.
+
+``install(project, destination)``
+---------------------------------
+
+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.
+
+``install_develop(project, destination)``
+-----------------------------------------
+
+Like install, but a develop egg is installed even if the current egg
+if not a develop egg.
+
+``Output normalization``
+------------------------
+
+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.
+
+
+``normalize_path``
+ Converts tests paths, based on directories created with tmpdir(),
+ to simple paths.
+
+``normalize_script``
+ 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.
+
+``normalize_egg_py``
+ Normalize Python version and platform indicators, if specified, in
+ egg names.