### ===========================================================================
### -package  : SimpleTest
# -version    : 0.2
# -purpose    : Regression testing framework.
# -overview   :
#     This package provides a complete framework for automated regression
#  testing.
#
#     Procedures are provided to initialise, reset and shutdown the test
#  environment, set criteria for test cases to be tested, actually perform the
#  test cases as well as others to obtain the test results and statistics.
#
# -usage      :
#     The K<::Simple::Test::initialise> procedure establishes a test
#  environment in the form of a slave interpreter in which the K<puts> command
#  has been modified so that the test cases output are collected.  Test cases
#  can be run in the test environment via the P<test-case> procedure.  By
#  comparing the output, errors and return values of the test cases with the
#  corresponding expected values each test is flagged as passed or failed. 
#
#     By using K<::Simple::Test::set-test-criteria>, one can set a criteria
#  for test cases to be tested or fully ignored.  The detailed test results
#  and the overall statistics are availabe via the P<::Simple::Test::results>
#  and P<::Simple::Test::statistics> procedures, respectively.
#
#     Use K<::Simple::Test::reset> to reset the test environment and
#  K<::Simple::Test::shutdown> to clean up after testing.
#
# -keywords   : regression test package procedure
# -variables  :
#
#  { CaseOutput       -string        {Output of each individual test case}}
#  { Results          -list          {List of tested tests cases tested each
#                                     one containing the following elements:
#                                        0: number
#                                        1: tag
#                                        2: title
#                                        3: whether it was skipped
#                                        4: whether it passed or failed
#                                        5: in case it failed, the diagnostics}}
#  { NTests           -int           {Number of tests cases tested}}
#  { NTestsPassed     -int           {Number of tests cases passed}}
#  { NTestsFailed     -int           {Number of tests cases failed}}
#  { NTestsSkipped    -int           {Number of tests cases skipped}}
#  { NTestsIgnored    -int           {Number of tests cases ignored}}
#  { TestExpr         -script        {Test cases to be tested expression}}
#
# -commands   :
#
#  * K<::Simple::Test::initialise>
#    Initialises the test environment.
#
#  * K<test-case> tag title ?-regexp? ?-prerequisites list? ?-setup script?
#    ?-script script? ?-cleanup script? ?-output any? ?-error any? ?-return any?
#    Performs a test case.
#
#  * K<::Simple::Test::set-test-criteria> testCriteria
#    Sets the criteria for test cases to be tested.
#
#  * K<::Simple::Test::criteria-to-expr> number criteria
#    Transforms a criteria into an expression.
#
#  * K<::Simple::Test::statistics>
#    Returns test statistics.
#
#  * K<::Simple::Test::results>
#    Returns the test results.
#
#  * K<::Simple::Test::reset>
#    Resets the test environment.
#
#  * K<::Simple::Test::shutdown>
#    Shutdowns the test environment.
#
#  * K<::Simple::Test::configure>
#    Configures the package options.
#
#  * K<::Simple::Test::cget>
#    Gets the package options.
#
# -examples   :
#
#  # Install the package
#  package require SimplePackage
#  ::Simple::Package::require-and-install SimpleTest
#  
#  # Initialise the test environment
#  ::Simple::Test::initialise
#  
#  # Set the test criteria: test cases number 1, 3 and following
#  ::Simple::Test::set-test-criteria 1,3-
#  
#  # Execute several test cases
#  
#  # This one passes
#  test-case test-case-1 {
#     First test case
#  } -setup {
#  
#     # Create a variable in the test environment
#     set foo 1
#  
#  } -script {
#        puts -nonewline $foo
#  } -output 1
#  
#  # This one is ignored
#  test-case test-case-2 {
#     Second test case
#  } -script {
#  } -output {}
#  
#  # This one fails
#  test-case test-case-3 {
#     Third test case
#  } -script {
#        return $foo
#  } -return 2
#  
#  # This one is skipped
#  test-case test-case-4 {
#     Fourth test case
#  } -prerequisites {
#     {$foo == 2}
#  } -script {
#  } -output {}
#  
#  # This one passes also
#  test-case test-case-5 {
#     Fifth test case
#  } -script {
#        error {ERROR MESSAGE}
#  } -cleanup {
#  
#     # Delete the variable in the test environment
#     unset foo
#  
#  } -error {ERROR MESSAGE}
#  
#  # This displays the following:
#  #    1 test-case-1     First test case: passed
#  #    2 test-case-2    Second test case: ignored
#  #    3 test-case-3     Third test case: failed
#  #    4 test-case-4    Fourth test case: skipped
#  #    5 test-case-5     Fifth test case: passed
#  foreach test [::Simple::Test::results] {
#  
#     # Get the test case information
#     foreach {number tag title ignored skipped passed diagnostics}\
#        $test break
#     if {$ignored} {
#        set status ignored
#     } elseif {$skipped} {
#        set status skipped
#     } elseif {$passed} {
#        set status passed
#     } else {
#        set status failed
#     }
#  
#     # Display a short report for each test case
#     puts [format {%1d %10s %20s %s} $number $tag $title: $status]
#  }
#  
#  # Final tests statistics
#  foreach {nTests passed failed skipped ignored}\
#     [::Simple::Test::statistics] break
#  
#  # Display some test cases statistics
#  # This displays the following:
#  #    Total test   cases 5
#  #    Test cases  passed 2
#  #    Test cases  failed 1
#  #    Test cases skipped 1
#  #    Test cases ignored 1
#  puts [format {Total test   cases %d} $nTests]
#  puts [format {Test cases  passed %d} $passed]
#  puts [format {Test cases  failed %d} $failed]
#  puts [format {Test cases skipped %d} $skipped]
#  puts [format {Test cases ignored %d} $ignored]
#  
#  # Shutdown the test environment
#  ::Simple::Test::shutdown
#
# -todo       :
#  * Consider whether it is worth it migrating the test infrastructure to use
#    the facilities of the Tcl test harness package.
#
#  * Add support for criteria for test cases to be tested based on the
#    test case tag.
#
# -history    :
#  19-feb-1999   Unreleased first version 0.1
#  23-apr-2000   First public release, version 0.2
#
# -copyright  :
#  Copyright (C) 1999, 2000, Juan C. Gil (jgil@gmv.es)
#
### ===========================================================================
