comment tag is used to comment/document your MScript.

There are two ways to add comments to mscript: comment attribute and xml comment tag.

For example:

  <if value1="$rand()" op="le" value2="0.5" comment="short comment1">
     <!--
        this is a long comments that may
        span multiple lines.
     -->
     <action code="$click('abc')" comment="short comment2"/>
  </if>

In the above example, if tag has a short comment “short comment”. Inside if, there is a 2-line comment right before action tag which also has a short comment “short comment2”.

The short comment entered in comment attribute is also used as the display label in Program Structure Diagram.

There is another use of comments besides being used to document your mscript. You may also use it to produce the test execution results by having them written out to a file as the mscript is executed. Because the comments can be nested inside another mscript tags, the comment will only be written (executed) when the enclosing mscript tag is executed. Essentially this is equivalent to placing log messages.

There are two ways to enable writing comments (xml comment tag) to a file:

• model property - enter a file name in TestCase Report File, use file extension .txt to output to a plain text file and .html for html web page.
• mScript function - call $enableCommentToSeqOut() or $setSeqOutFile() to enable writing out comments to the file.

You may use any mScript functions inside the comments. They will be executed if write comments to file is enabled. This gives you the ability to construct the comment text to be written out to the file just like log message.

For example:

  <if value1="$getTitle()" op="eq" value2="Product List">
    <then>
       <!--
           We landed at "Product List" page.
           Passed at Transition [curTransEvent], Requirement tag [curTransTags]
       -->
       <action code="$addTagCheck('[curTransTags]', 'passed')"/>
    </then>
    <else>
       <!--
           We landed at "$getTitle()" page, expecting "Product List".
           Failed at Transition [curTransEvent], Requirement tag [curTransTags]
           Traces that led to this failure:
              Traversal Path: @a width='100%'|$genPath('failurreTraceSeq')@
              Sequence Diagram: @a|$genMSC('Product List Page Failure', 'failureTraceMSC')@
       -->
       <action code="$addTagCheck('[curTransTags]', 'failed')"/>
    </else>
  </if>

In the above example, assuming current transition name is clickMain and requirements tag associated with the transition is “R_1; R_2”, it will print the following to the file if if tag evaluates to true:

         We landed at "Product List" page.
         Passed at Transition clickMain, Requirement tag R_1; R_2

or print the following if if evaluates to false (say landed on Item Detail page):

         We landed at "Item Detail" page, expecting "Product List"
         Failed at Transition clickMain, Requirement tag R_1; R_2
         Traces that led to this failure:
            Traversal Path: http://testoptimal.com/img/failureTraceSeq.png
            Sequence Diagram: http://testoptimal.com/img/failureTraceMSC.png

The above information written to the file would capture the test result success or failures and the graphs produced above would provide the documentation of the test results as well as useful information you can pass to the developer to reproduce the failure.