From 21648313a7d8564dacdc6e04764e56fc116259ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jurko=20Gospodneti=C4=87?= Date: Thu, 1 May 2008 17:08:04 +0000 Subject: [PATCH] Updated the Boost Build test system documentation. Now all the command line options are described. Several function descriptions updated. [SVN r44983] --- test/test_system.html | 334 +++++++++++++++++++++++++----------------- 1 file changed, 203 insertions(+), 131 deletions(-) diff --git a/test/test_system.html b/test/test_system.html index a897d4f37..1b1faab92 100644 --- a/test/test_system.html +++ b/test/test_system.html @@ -12,14 +12,14 @@ @@ -34,6 +34,12 @@
Introduction for users
+
+
+
Command line options
+
+
+
Introduction for developers
@@ -41,8 +47,8 @@
Changing the working directory
-
Examining the working directory - and changing it
+
Examining the working directory and + changing it
Test result
@@ -87,14 +93,13 @@

Introduction for users

-

The testing system for Boost.Build is a small set of Python modules - and scripts for automatically testing user-obversable behaviour. It uses - components from testing systems of Scons and Subversion, together with some - additional functionality.

+

The testing system for Boost.Build is a small set of Python modules and + scripts for automatically testing user-obversable behaviour. It uses + components from testing systems of Scons + and Subversion, together with + some additional functionality.

-

To run the tests you'd need:

+

To run the tests you need to:

  1. Get the source tree of Boost.Build (located at tools/build @@ -115,25 +120,47 @@ for testing.
-

When all is done, you can run the tests with

+

When all is set, you can run all the tests using the test_all.py + script or you can run a specific test by starting its Python script + directly.

+ +

Examples:

+ 
 python test_all.py
-
- -

which will use the default toolset, or you can specify toolset on the - command line, for example:

-
-python test_all.py borland
-
- -

If everything's OK, you'll see a list of passed tests. Otherwise, a - failure will be reported.

- -

It is possible to run a specific test, for example:

-
 python generators_test.py
+

If everything is OK, you will see a list of passed tests. Otherwise, a + failure will be reported.

+ +

Command line options

+ +

Test scripts will use the toolset you configured to be the default or + you can specify a specific one on the command line:

+ +
+python test_all.py borland
+python generators_test.py msvc-7.1
+
+ +

Other test script flags you can specify on the command line are:

+ + +

Introduction for developers

It is suggested that every new functionality come together with tests, @@ -144,28 +171,28 @@ python generators_test.py

  • For an interpreted language like Jam, without any static checks, testing is simply the only sefeguard we can have.
    • -
  • Good tests allow to change internal design much more safely, and we - didn't nailed everything down yet.
    • +
  • Good tests allow us to change internal design much more safely, and we + have not gotten everything nailed down yet.

    • Adding a new test is simple:

    1. Go to $boost_build_root/test/test_all.py and add new test - name to the list at the end of file. Suppose the test name is - "hello".
      2. + name to the list at the end of the file. Suppose the test name is "hello". + -
    2. Add a new python module, in this example "hello.py", to do actual +
    3. Add a new python module, in this example "hello.py", to do the actual testing.

    The module, in general will perform these basic actions:

      -
    1. Setting the initial working directory state
      2. +
    2. Set up the initial working directory state
    3. - Running the build system and checking: + Run the build system and check the results:
      1. generated output,
        2. @@ -176,10 +203,10 @@ python generators_test.py
      4. -
    4. Adding, removing or touching files, or changing their content and - then repeating the previous step, until satisfied.
      5. +
    5. Add, remove or touch files or change their content and then repeat + the previous step until satisfied.
      6. -
    6. Cleaning up
      7. +
    7. Clean up

    The "hello.py" module might contain:

    @@ -204,12 +231,12 @@ int main() t.run_build_system() -# First, create a list of three pathnames +# First, create a list of three pathnames. file_list = List("bin/$toolset/debug/") * List("hello.exe hello.obj") # Second, assert that those files were added as result of the last build system invocation. t.expect_addition(file_list) -# Invoke the build system once again +# Invoke the build system once again. t.run_build_system("clean") # Check if the files added previously were removed. t.expect_removal(file_list) @@ -221,18 +248,18 @@ t.cleanup()

    The test directory contains a file "template.py" which can be used as a start for your own tests.

    -

    Overview of the most important methods of class - TestBoostBuild follows.

    +

    Overview of the most important methods of class Tester follows. +

    Changing the working directory

    -

    The class TestBoostBuild creates a temporary directory in its +

    The class Tester creates a temporary directory in its constructor and changes to that directory. It can be modified by calling these methods: