From 1bc53371569dbf3b8b8a23f5a6697be4ee8de2cb Mon Sep 17 00:00:00 2001 From: Johan Holmberg Date: Tue, 12 May 2009 19:02:20 +0000 Subject: [PATCH] add more info about command line usage --- doc/cmdtest.html | 82 +++++++++++++++++++++++++++++++++++++++--------- doc/cmdtest.txt | 57 ++++++++++++++++++++++++++++++++- 2 files changed, 123 insertions(+), 16 deletions(-) diff --git a/doc/cmdtest.html b/doc/cmdtest.html index eb4cbf2..cbfd49a 100644 --- a/doc/cmdtest.html +++ b/doc/cmdtest.html @@ -307,15 +307,16 @@ ul.auto-toc {
  • Matching standard output content
  • Invoking cmdtest
    • -
  • Reference Part @@ -520,6 +521,7 @@ for string equality
    • for CMDTEST_*.rb files in the following places:

    1. first t/CMDTEST_*.rb
      2. +
    2. second test/CMDTEST_*.rb
    3. otherwise CMDTEST_*.rb

    If some command line arguments have been given, cmdtest will use @@ -530,6 +532,26 @@ $ cmdtest CMDTEST_foo.rb CMDTEST_bar.rb # two files $ cmdtest t # all CMDTEST_*.rb files in "t" dir $ cmdtest . t # all CMDTEST_*.rb files in both dirs +

    In addition to test files, the command line can also contain options +and testcase selectors. The general format is:

    +
    +$ cmdtest [options] [files] [selectors]
+
    +

    The options are describe in a separate section below. The selectors are +regular expressions that are used to match the names of the test +methods. It is best illustrated by an example:

    +
    +$ cmdtest examples "/stdin|stdout/"
+
    +

    This command will find all files matching examples/CMDTEST_*.rb, +and run all test methods whose names either contain the string "stdin" +or "stdout". As can be seen in the example, the regular expression may +need protection from expansion by the shell (that is the reason for +the quotes in the example). But the example can also be written:

    +
    +$ cmdtest examples /stdin/ /stdout/
+
    +

    For more examples of command line usage, see the section Commandline Examples below.

    Options

    @@ -566,11 +588,41 @@ have changed since last time.
    +
    +

    Commandline Examples

    +

    This section is a collection of examples of how Cmdtest can be used.

    +
    +$ cmdtest
+
    +

    This is the most basic usage. All testcase files found (by the +algorithm described earlier) will be executed.

    +
    +$ cmdtest -i
+
    +

    Only run the test methods that have failed earlier, or have changed. +This is not a full-blown "make system", but may still be useful when +developing the tests.

    +
    +$ cmdtest /stdout/
+
    +

    Run all test methods matching the regular expression given.

    +
    +$ cmdtest examples
+
    +

    Run all tests found in test files in the "examples" directory +(i.e. examples/CMDTEST_*.rb).

    +
    +$ cmdtest --xml=reports/test-foo.xml
+
    +

    Write an XML-summary to the specified file. The file uses the same +format as JUnit, so it can be understood be continuous integration +servers such as Hudson.

    +
    -

    Reference Part

    +

    Reference Part

    -

    cmd

    +

    cmd

    The cmd method is the central method of the whole Cmdtest framework. It should always be called with a block like this:

    @@ -597,7 +649,7 @@ end
 
    See also the example in the Structure of a test-method section above.
    -

    Assertions - exit status

    +

    Assertions - exit status

    exit_nonzero
    The command should have exited with a non-zero exit status (i.e. it @@ -611,7 +663,7 @@ exit-related methods have been called.
    -

    Assertions - files

    +

    Assertions - files

    affected_files(file1,...,fileN)
    The specified files should have been created, removed or modified by the @@ -637,7 +689,7 @@ case special (when the file is created).
    -

    Assertions - stdout/stderr/file content

    +

    Assertions - stdout/stderr/file content

    file_equal(file, content)
    Assert that the specified file matches the given content. @@ -661,7 +713,7 @@ For more details and examples see the section "Matching standard output con
    -

    Assertions - misc

    +

    Assertions - misc

    assert(flag, msg=nil)
    Assert that flag is true. This assertion is a last resort, when no other @@ -672,7 +724,7 @@ interval given as argument.
    -

    Helper functions

    +

    Helper functions

    create_file(filename, content)
    Create a file inside the "work directory". @@ -711,7 +763,7 @@ time of the call.
    View document source. -Generated on: 2009-05-10. +Generated on: 2009-05-12. Generated by Docutils from reStructuredText source.
    diff --git a/doc/cmdtest.txt b/doc/cmdtest.txt index 8256bd8..f1b9531 100644 --- a/doc/cmdtest.txt +++ b/doc/cmdtest.txt @@ -224,7 +224,9 @@ for ``CMDTEST_*.rb`` files in the following places: 1) first ``t/CMDTEST_*.rb`` -2) otherwise ``CMDTEST_*.rb`` +2) second ``test/CMDTEST_*.rb`` + +3) otherwise ``CMDTEST_*.rb`` If some command line arguments have been given, ``cmdtest`` will use them instead of searching by itself. Some examples:: @@ -234,6 +236,27 @@ them instead of searching by itself. Some examples:: $ cmdtest t # all CMDTEST_*.rb files in "t" dir $ cmdtest . t # all CMDTEST_*.rb files in both dirs +In addition to test files, the command line can also contain options +and testcase selectors. The general format is:: + + $ cmdtest [options] [files] [selectors] + +The options are describe in a separate section below. The selectors are +regular expressions that are used to match the names of the test +methods. It is best illustrated by an example:: + + $ cmdtest examples "/stdin|stdout/" + +This command will find all files matching ``examples/CMDTEST_*.rb``, +and run all test methods whose names either contain the string "stdin" +or "stdout". As can be seen in the example, the regular expression may +need protection from expansion by the shell (that is the reason for +the quotes in the example). But the example can also be written:: + + $ cmdtest examples /stdin/ /stdout/ + +For more examples of command line usage, see the section `Commandline Examples`_ below. + Options +++++++ @@ -265,6 +288,38 @@ Options Cmdtest will try to run only those test methods that are failed or have changed since last time. + +Commandline Examples +++++++++++++++++++++ + +This section is a collection of examples of how Cmdtest can be used. :: + + $ cmdtest + +This is the most basic usage. All testcase files found (by the +algorithm described earlier) will be executed. :: + + $ cmdtest -i + +Only run the test methods that have failed earlier, or have changed. +This is not a full-blown "make system", but may still be useful when +developing the tests. :: + + $ cmdtest /stdout/ + +Run all test methods matching the regular expression given. :: + + $ cmdtest examples + +Run all tests found in test files in the "examples" directory +(i.e. ``examples/CMDTEST_*.rb``). :: + + $ cmdtest --xml=reports/test-foo.xml + +Write an XML-summary to the specified file. The file uses the same +format as JUnit_, so it can be understood be continuous integration +servers such as Hudson_. + Reference Part --------------