diff -r 5ff1fc726848 -r c6bca38c1cbf eggs/zc.buildout-1.5.2-py2.6.egg/zc/buildout/testing.txt --- /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.