T4S4  18.1 C7177 A20283
Teamcenter Gateway for SAP S/4HANA API Reference
T4X::TestingSupport Namespace Reference

Commands to work with the Test and Teach framework (TNT). More...

Namespaces

 Assert
 Commands to compare expected with actual results. They must only be called from within verify procedures. Call them without any namespace identifier.
 
 DemoCase
 Commands to retrieve information about the demo case currently being executed. They must only be called from within demo case namespaces.
 
 DemoSuite
 Commands to retrieve information about the demo suite currently being executed. They must only be called from within demo case namespaces.
 

Functions

 canExecuteDemoSuite namespace ?optionsVar?
 Test whether all preconditions defined in a demo suite are met. More...
 
 executeDemoSuite namespace testResultsVar ?optionsVar?
 Execute demo suite as a test. More...
 
 executeTests args
 Execute demo suite as a test (deprecated). More...
 
 formatTestReport testResultsVar
 Format the test results into a list of lines. More...
 
 getNonGood testResultsIn
 Returns the list of demo cases that did not complete with GOOD. More...
 
 htmlCloseFile channel ?optionsVar?
 Close an HTML file opened to receive the documentation to be generated through the htmlWriteLessons command. More...
 
 htmlOpenFile htmlOutputFileName ?optionsVar?
 Open an HTML file to receive the documentation to be generated through the htmlWriteLessons command. More...
 
 htmlWriteLessons channel namespace patterns ?optionsVar?
 Derive documentation from a demo suite and write it to an HTML file. More...
 
 logTestReport testResultsVar ?logChannel?
 Output test results using the tpwrite command. More...
 
 putCode namespace patterns ?optionsVar?
 Generate code for the test cases specified through the given patterns and output the code using the puts command. More...
 
 putLessons namespace patterns ?optionsVar?
 Output the title, lesson and code parts of demo suite using the puts command. More...
 
 putOverview namespace patterns ?optionsVar?
 Output the title, and code parts of demo suite using the puts command. More...
 
 putTestReport testResultsVar
 Output test results using the puts command. More...
 

Detailed Description

Commands to work with the Test and Teach framework (TNT).

Demo Suites and Demo Cases

Formulate demo suites containing demo cases, similar to test suites and test cases, and feed them into the TNT using the commands in this namespace. The result will be the execution of the tests with a test report you can output or documentation in several formats.

The demo suites are specified as Tcl namespaces including subordinate namespaces for the demo cases. The demo case namespaces may include the following pieces:

  • title variable - A brief description of what the commands used in the test do. Each line may start with a hash symbol ("#"). This way Tcl-Editors can format the descriptive text as they do with Tcl comments.
  • description variable - Text that describes the demo case. Formatted the same way as the title field.
  • lesson variable - Text that explains the commands used in the demo case in detail. Each line may start with a hash symbol ("#") like in the title field. In addition markup symbols contained in the text are interpreted it the output format is HTML. See markup.
  • note variable - Short note that will be output if the execution of a demo case succeeded.
  • testBefore variable - list of demo cases which must have been executed prior to running this demo case. See also depends variable below.
  • knowBefore variable - list of demo cases the lessons of which should have been read before reading the lesson of this test. See also depends variable below.
  • depends variable - list of tests which you would enter into testBefore as well as readBefore can be put here.
  • precondition procedure - The code defined in this procedure is executed prior to executing the code to be tested. It must return a true boolean if the the actual code can be executed or false if it cannot. See Preconditions below. The code in a precondition procedure must not depend on results from code to be executed as a test.

    Example:

    1 namespace eval GeneralWsdlImportTest {
    2  [...]
    3  proc precondition {} {
    5  file isdirectory $inputDir
    6  }
    7  [...]
    8 }
  • code procedure - The code to execute for the demo case. It may use variables set in dependent demo cases and set variables for other demo cases and for the verify section.
  • examples procedure - Additional code not executed for the test but shown to give more examples of how the commands under test may be used.
  • bad procedure - This code is executed in the course of a test like code. It is however expected to throw an error. This is used to verify that a particular error condition gets recognized.
  • verify procedure - The code to verify the results raised in the code section. It may contain calls to the Assert::assertEquals, Assert::assertTrue, Assert::assertFalse, etc. procedures to verify the correctness of values produced by the test objects.
  • lazy variable - If set to true this demo case will not be executed unless
    • it is a dependency of another demo case or
    • it is found by a filter

How to interpret Test Results

Test results are recorded in the testResults array the name of which is passed to the commands as a parameter. Demo cases are assigned so called four-letter-status-words out of the following:

  • FAIL - A test executed with error
  • DAMN - A precondition test threw an error
  • ARGH - A precondition is not met
  • OUCH - A test threw an error
  • OUPS - The verification code threw an error
  • GOOD - No test executed with an error or failed assertion
  • DEPS - A test can't execute because dependencies didn't complete successfully
  • SKIP - A test is not executed as filtered out by filter pattern
  • WAIT - A test has not yet been executed (this is here for the sake of completeness, you will normally never see this state in the output)

Preconditions

The precondition procedures can be used to define preconditions that must be met before the code defined in the code procedures get executed. The canExecuteDemoSuite can then be called prior to running any test in order to check if there are unmet preconditions. This is for example useful to test if test data required to execute the demo suite is available. If it is not the test script may not even offer the possibility to execute the demo suite

For this to work the code in a precondition procedure must not depend on results from code to be executed as a test. Only then all precondition procedures can be executed to verify if the demo suite can be executed.

Read more (including examples) under also precondition proc and canExecuteDemoSuite command.

Angle Bracket Expressions

All procedures defined in a demo case such as code, precondition, verify or examples may contain placeholders of the form <%= SCRIPT%>. The SCRIPT is a piece of Tcl code that is executed when the code is retrieved from the body of the procedure. The result of the execution replaces the placeholder. This can be used for example to avoid code duplication.

Hiding Lines from Output

If you want lines in the code procedure to not appear in the representation used for documentation purposes you can suppress them with the following markers:

  • Enclose one or multiple line in markers
    1 #HIDE ON#
    2 ... lines to be hidden ...
    3 #HIDE OFF#
  • Add a marker to the end of a line
    1 line to be hidden; #HIDE#

Lightweight Markup Language (LWL)

The htmlWriteLessons command produces HTML output from text placed into lessons. The lessons are parsed by a simple markup processor that translates the markup into HTML elements.

The following markup elements are supported:

  • Text between apostrophes will be formatted as code, e.g.

    The value is 'true' → The value is true

  • Text between asterisk will be output in bold font, e.g.

    Click on *File* → Click on File

  • Text between double pairs of angle brackets will be output in italic font, e.g.

    This is called a <<demo case>> → This is called a demo case

  • Two dashes and an angle bracket will be output as a right arrow, e.g.

    Go to File –> New ... → Go to File → New ...

  • A single dash and an angle bracket followed by the name of a demo case creates a link in the output document, e.g.

    See ->FindBomHeader → See Find the header of a Bill Of Material (BOM)

  • The pattern --! Caution ! on a single line followed by any number of dashes marks the beginning of highlighted text. The end of the highlighted text is marked with a single line consisting of at least six dashes, e.g.:

    --! Caution !–—
    NOTE THAT ...
    ---------------—

    is rendered as
NOTE THAT ...
  • A line beginning with an asterisk denotes a list item
  • It is possible to create simple tables in the output document, e.g.
    1 +=================+==================+
    2 |contextType | type of stucture |
    3 +=================+==================+
    4 |MEProductContext | Bill of Material |
    5 +-----------------+------------------+
    6 |MEPlantContext | Plant |
    7 +-----------------+------------------+
    8 |MEProcessContext | Bill of Processes|
    9 +=================+==================+

(There are bugs in the Doxygen document generator that disallow displaying the HTML output here)

Function Documentation

◆ canExecuteDemoSuite()

T4X::TestingSupport::canExecuteDemoSuite   namespace ?optionsVar?  

Test whether all preconditions defined in a demo suite are met.

If you are interested in more details you can use the executeDemoSuite command with the execute option set to false and extract the details from the result array.

  • Example:
    1 if {[::T4X::TestingSupport::canExecuteDemoSuite ::WsdlImportDemo]} {
    2  puts "Test data found"
    3  set action TEST
    4  set actions [concat [list {TEST Execute automatic test}] $actions]
    5  set usageHint [concat {TEST} $usageHint]
    6 } else {
    7  puts "Cannot execute without test data"
    8  set action TEACH
    9 }
Parameters
namespacethe Tcl namespace representing the demo suite
optionsVar(optional) name of an array variable from which to read further options. Supported options are given with the executeDemoSuite command.
Returns
true if all preconditions are met, false if any is not met.

References executeDemoSuite().

◆ executeDemoSuite()

T4X::TestingSupport::executeDemoSuite   namespace testResultsVar ?optionsVar?  

Execute demo suite as a test.

If the optionsVar parameter is given it is interpreted as the name of an array that may contain the following entries:

  • executionContext - namespace inside which the tests are executed; defaults to the namespace given as the first argument
  • patterns - List of patterns to be applied to the names of demo cases (the names of the namespaces) to select which demo cases to process; defaults to the empty string in which case all non lazy demo cases are selected.
  • testPrecondition - If set to true test if all preconditions are met and write the result into the preconditionsMet field of the result array; defaults to false.
  • execute - If set to false no demo case will be tested. This is used in conjunction with testPrecondition to only check the preconditions.
  • testDataRoot - The path name of the folder where the TNT framework expects test data. Defaults to 'var/testdata' inside the T4x installation. The test data is used for comparisons with Assert::assertTextFilesEqual.
  • outputCodeUnderTest - If set to true the code that is being tested will be output. This is useful to verify if the angle bracket expressions" are expanded in the expected way.
Parameters
namespacethe Tcl namespace representing the demo suite
testResultsVarname of an array variable into which the test result is recorded
optionsVar(optional) name of an array variable from which to read further options. Supported options are given above.

References GetBool(), and XGet().

Referenced by canExecuteDemoSuite(), and executeTests().

◆ executeTests()

T4X::TestingSupport::executeTests   args  

Execute demo suite as a test (deprecated).

Deprecated:
Use executeDemoSuite instead as it supports the preferred way of passing in options.
Parameters
namespacethe Tcl namespace representing the demo suite
executionContextnamespace inside which the tests are executed
testResultsVarname of an array variable into which the test result is recorded
patterns(optional) list of patterns to be applied to the names of demo cases (the names of the namespaces) to select which demo cases to process. The string match command is used for this and case is ignored.

References executeDemoSuite().

◆ formatTestReport()

T4X::TestingSupport::formatTestReport   testResultsVar  

Format the test results into a list of lines.

Parameters
testResultsVarname of an array variable containing the test results as produced by the executeDemoSuite command.

Referenced by logTestReport(), and putTestReport().

◆ getNonGood()

T4X::TestingSupport::getNonGood   testResultsIn  

Returns the list of demo cases that did not complete with GOOD.

◆ htmlCloseFile()

T4X::TestingSupport::htmlCloseFile   channel ?optionsVar?  

Close an HTML file opened to receive the documentation to be generated through the htmlWriteLessons command.

Parameters
channelidentifier representing the HTML file
optionsVar(optional) name of an array variable from which to read further options. Not used currently.

◆ htmlOpenFile()

T4X::TestingSupport::htmlOpenFile   htmlOutputFileName ?optionsVar?  

Open an HTML file to receive the documentation to be generated through the htmlWriteLessons command.

Parameters
htmlOutputFileNamefull path of the HTML file
optionsVar(optional) name of an array variable from which to read further options. Not used currently.
Returns
a channel identifier representing the HTML file

◆ htmlWriteLessons()

T4X::TestingSupport::htmlWriteLessons   channel namespace patterns ?optionsVar?  

Derive documentation from a demo suite and write it to an HTML file.

Parameters
channelidentifier representing the HTML file
namespacerepresenting the demo suite
patterns(optional) list of patterns to be applied to the names of demo cases (the names of the namespaces) to select which demo cases to process. The string match command is used for this and case is ignored.
optionsVar(optional) name of an array variable from which to read further options. Not used currently.

References PutTestSpecs(), and SetDefault().

◆ logTestReport()

T4X::TestingSupport::logTestReport   testResultsVar ?logChannel?  

Output test results using the tpwrite command.

The log lines are assigned a message type according to the status of the tests.

Parameters
testResultsVarname of an array variable containing the test results as produced by the executeDemoSuite procedure.
logChannel(optional) identifier of the log file to write to.

References formatTestReport(), and tpwrite().

◆ putCode()

T4X::TestingSupport::putCode   namespace patterns ?optionsVar?  

Generate code for the test cases specified through the given patterns and output the code using the puts command.

The generated code may be copied into real mappings but may have to be reworked afterwards.

Parameters
namespacerepresenting the demo suite
patterns(optional) list of patterns to be applied to the names of demo cases (the names of the namespaces) to select which demo cases to process. The string match command is used for this and case is ignored.
optionsVar(optional) name of an array variable from which to read further options. This command only interprets the executionContext option. Supported options are given with the executeDemoSuite command.

References PutTitleWithPrefix(), and XGet().

◆ putLessons()

T4X::TestingSupport::putLessons   namespace patterns ?optionsVar?  

Output the title, lesson and code parts of demo suite using the puts command.

The demo cases are taken from the namespace from which this command is called.

If the optionsVar parameter is given it is interpreted as the name of an array that may contain the following entries:

  • executionContext - namespace inside which the tests are executed; defaults to the namespace given as the first argument
  • textWidth maximum number of characters to use to display a single line of output. Defaults to 80.
Parameters
namespacerepresenting the demo suite
patterns(optional) list of patterns to be applied to the names of demo cases (the names of the namespaces) to select which demo cases to process. The string match command is used for this and case is ignored.
optionsVar(optional) name of an array variable from which to read further options. Supported options are given above.

References PutTestSpecs().

◆ putOverview()

T4X::TestingSupport::putOverview   namespace patterns ?optionsVar?  

Output the title, and code parts of demo suite using the puts command.

If the optionsVar parameter is given it is interpreted as the name of an array that may contain the following entries:

  • executionContext - namespace inside which the tests are executed; defaults to the namespace given as the first argument
  • textWidth maximum number of characters to use to display a single line of output. Defaults to 80.
Parameters
namespacerepresenting the demo suite
patterns(optional) list of patterns to be applied to the names of demo cases (the names of the namespaces) to select which demo cases to process. The string match command is used for this and case is ignored.
optionsVar(optional) name of an array variable from which to read further options. Supported options are given above.

References PutTestSpecs().

◆ putTestReport()

T4X::TestingSupport::putTestReport   testResultsVar  

Output test results using the puts command.

Parameters
testResultsVarname of an array variable containing the test results as produced by the executeDemoSuite procedure.

References formatTestReport().