Using Test Case Documentation

When Jameleon sees a tag it doesn't recognize, it fails during execution. This can have undesired affects in your script. As discussed in Documenting Scripts, when a test script is selected, the documentation is generated and displayed to the right. The Execution Steps area explains what Jameleon sees when running the script. This is one of the areas where having a unique functionId attribute for each tag is helpful. You can use this documentation to validate that each functionId in your script is displayed in test Execution Steps.

Let's misspell ju-assert-equals as ju-assert-equal, keeping a valid XML document, but giving Jameleon a tag it doesn't know about.

<testcase xmlns="jelly:jameleon">

    <test-case-summary>
        An example passing test that simply compares two equal values.
    </test-case-summary>
    <test-case-author>Joe Blow</test-case-author>
    <test-case-level>FUNCTIONAL</test-case-level>
    <functional-point-tested>assert-equals</functional-point-tested>
    <test-case-bug>12345</test-case-bug>
    <application-tested>JUnit Plug-in</application-tested>
    <test-case-requirement>#AF323</test-case-requirement>

    <ju-session>
        <function-doc>extra step to document</function-doc>
        <ju-assert-equal
            functionId="Compare two equaling variables"
            expected="value 1"
            actual="value 1"/>
    </ju-session>
</testcase>
                        

Save this file as brokenScript.xml in the scripts folder. When a new file is created, you must double-click on the parent of where the scripts exists to see the script. Because the parent of this script is Test Cases, we need to double-click Test Cases two times to see the new file.

Notice that the second functionId doesn't show up in the documentation. The function may get skipped when generating the docs, but when executing the script, you will get a failure at that tag.

Now let's go over an example with invalid XML. Misspell the opening ju-session as ju-sessio, but leave the closing ju-session tag alone and see the results.

<testcase xmlns="jelly:jameleon">

    <test-case-summary>
        An example passing test that simply compares two equal values.
    </test-case-summary>
    <test-case-author>Joe Blow</test-case-author>
    <test-case-level>FUNCTIONAL</test-case-level>
    <functional-point-tested>assert-equals</functional-point-tested>
    <test-case-bug>12345</test-case-bug>
    <application-tested>JUnit Plug-in</application-tested>
    <test-case-requirement>#AF323</test-case-requirement>

    <ju-sessio>
        <function-doc>extra step to document</function-doc>
        <ju-assert-equals
            functionId="Compare two equaling variables"
            expected="value 1"
            actual="value 1"/>
    </ju-session>
</testcase>
                        

While the message in the dialog box isn't exactly intuitive, it does say that there is an opening ju-sessio, but not a closing one, thus creating an invalid XML document. Now it's up to you to figure out which tag is the correct one, ju-sessio or ju-session.

Using Debug Mode

Often times, your script is failing and you don't know for sure what is going on. In debug mode, you can step through the execution of your script and change the values of variables real-time. Currently, the variables with multiple values (arrays, Lists, HashMaps ...) are not supported in this mode.

Let's start off by debugging the above example. To use the debug mode, you must set an attributed called breakPoint to true in the function tag you want to start debugging. Currently, this attribute can only be set in function and data-drivable tags. The function-doc tag is actually a function tag. Let's tell the debugger to start there by changing the above script to:

<testcase xmlns="jelly:jameleon">

    <test-case-summary>
        An example passing test that simply compares two equal values.
    </test-case-summary>
    <test-case-author>Joe Blow</test-case-author>
    <test-case-level>FUNCTIONAL</test-case-level>
    <functional-point-tested>assert-equals</functional-point-tested>
    <test-case-bug>12345</test-case-bug>
    <application-tested>JUnit Plug-in</application-tested>
    <test-case-requirement>#AF323</test-case-requirement>

    <ju-session>
        <function-doc breakPoint="true">extra step to document</function-doc>
        <ju-assert-equal
            functionId="Compare two equaling variables"
            expected="value 1"
            actual="value 1"/>
    </ju-session>
</testcase>
                        

To run the script in debug mode, select the script to debug and press the Debug Test(s) button. This button is highlighted below.

After pressing the debug button, you should be prompted with a dialog box telling you which tag you are on as well as all variables that are settable in that tag. Below is the dialog that you should see after pressing the debug button:

The title of the dialog is the functionId of the tag being debugged. Below the title is the name of the tag and below that is a table that represents the variables that can be set and their corresponding values. I moved the debug dialog to the top-right in order to see the script. Notice that the functional point that we are on is highlighted in the script. If you press the Go button, the debugger will continue on until it finds another break point or until the script ends. If you press the Step button, then the debugger will stop at the next function tag with a similar prompt.

In our example, it doesn't matter whether we press Go or Step because the second tag is misspelled and not recognized by Jameleon. Let's fix that by changing ju-assert-equal back to ju-assert-equals, saving the file and then pressing the debug button again. If you press the Step button again, a dialog box will appear for the ju-assert-equals tag.

To better understand the debug functionality, experiment with changing the values in the debug dialog window for the ju-assert-equals tag and make it fail.

NOTE: You must hit the Enter key or select another cell to commit the changes that you made in the debug dialog window.