1 Testing Support

     2 ===============

     3 

     4 The zc.buildout.testing module provides an API that can be used when

     5 writing recipe tests.  This API is documented below.  Many examples of

     6 using this API can be found in the zc.buildout, zc.recipe.egg, and

     7 zc.recipe.testrunner tests.

     8 

     9 zc.buildout.testing.buildoutSetUp(test)

    10 ---------------------------------------

    11 

    12 The buildoutSetup function can be used as a doctest setup function.

    13 It creates a sample buildout that can be used by tests, changing the

    14 current working directory to the sample_buildout. It also adds a

    15 number 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 

   135 Tear down everything set up by zc.buildout.testing.buildoutSetUp.  Any

   136 functions passed to register_teardown are called as well.

   137 

   138 ``install(project, destination)``

   139 ---------------------------------

   140 

   141 Install eggs for a given project into a destination.  If the

   142 destination is a test object, then the eggs directory of the

   143 sample buildout (sample_buildout) defined by the test will be used.

   144 Tests will use this to install the distributions for the packages

   145 being tested (and their dependencies) into a sample buildout. The egg

   146 to be used should already be loaded, by importing one of the modules

   147 provided, before calling this function.

   148 

   149 ``install_develop(project, destination)``

   150 -----------------------------------------

   151 

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

   153 if not a develop egg.

   154 

   155 ``Output normalization``

   156 ------------------------

   157 

   158 Recipe tests often generate output that is dependent on temporary file

   159 locations, operating system conventions or Python versions.  To deal

   160 with these dependencies, we often use

   161 zope.testing.renormalizing.RENormalizing to normalize test output.

   162 zope.testing.renormalizing.RENormalizing takes pairs of regular

   163 expressions and substitutions. The zc.buildout.testing module provides

   164 a few helpful variables that define regular-expression/substitution

   165 pairs 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.