8.2. Writing Testcases

In this section it will be described how agent-based testcases can be written. The test agents can be executed either in the testcenter tool, or as they are normal agents in the starter tool. If you start them in the starter tool, the test output will be written to the console.

For the construction of a testable agent it is necessary to include (and make available) functionality of the jadex.planlib.Test capability. In general, this capability is responsible for collecting user-defined jadex.planlib.TestReports and sends them back to the test center after all tests of a test agents have been carried out. Conceretely, a test agent has to import resp. reference the following elements of the Test capabiliy:

In the following a template ADF is depicted that shows exactly how the described elements need to be included:
...
<capabilities>
    <capability name="testcap" file="jadex.planlib.Test"/>
    ...
</capabilities>

<beliefs>
    <beliefsetref name="reports" class="TestReport">
        <concrete ref="testcap.reports"/>
    </beliefsetref>
    <beliefref name="testcase_cnt" class="int">
        <concrete ref="testcap.testcase_cnt"/>
    </beliefref>
    <beliefref name="timeout" class="long" exported="true">
        <concrete ref="testcap.timeout"/>
    </beliefref>
    <beliefref name="testcenter" class="jadex.adapter.fipa.AgentIdentifier" exported="true">
        <concrete ref="testcap.testcenter"/>
    </beliefref>
    ...
</beliefs>

<configurations>
    <configuration name="default">
        <beliefs>
            <initialbelief ref="testcase_cnt">
                <fact>...</fact> <!-- Here the actual number of testcases needs to be entered. -->
            </initialbelief>
        </beliefs>
        <plans>
            <initialplan ref="test"/>
        </plans>
    </configuration>
</configurations>
...		

Figure 8.6.  The ADF of a testable agent

Besides the test preparation the test cases have to be written in a plan which normally is defined also as initial plan of the test agent. In the following code snippet (Figure 8.7, “ The plan for a testable agent ”) it is depicted what steps usually make up one test case.

...
public void body()
{
    ...
    TestReport tr = new TestReport("#1", "The description of what is tested.");
    
    try
    {
        // Test code goes here, e.g.:
        // IGoal mygoal = createGoal("my_goal");
        // dispatchSubgoalAndWait(mygoal);
        tr.setSucceeded(true);
    }
    catch(GoalFailureException e)
    {
        tr.setFailed("Exception occurred: " + e);
    }
    getBeliefbase().getBeliefSet("reports").addFact(tr);
}
...

Figure 8.7.  The plan for a testable agent

The test plan should take care of creating a test report (jadex.planlib.TestReport) before the actual test code and initialize it with a name (e.g. the number of the test) and a short description of what is to be tested (both appear in the test report details).

Below that setup code the domain dependent test code can be placed. Usually, it is advantageous surrounding that test code with a try-catch block so that any occurring exception can be handled and the plan is capable of continuing with the execution of futher test cases from the same plan.

If the execution of the test was successful (e.g. when no exception occurred and the results are as expected), this should be marked in the test report via the setSucceeded(true) method. In case of a failure, the setFailed()-method can be used. It requires an error description to be given as parameter.

The test case execution is finished by adding the corresponding test report to the “reports”-beliefset (see Figure 8.6, “ The ADF of a testable agent ”) by calling getBeliefbase().getBeliefSet("reports").addFact(tr);. The test agent won't terminate successfully until the last report is added to the “reports”-beliefset.

If you want to do any cleanup operations before terminating, this should be done before adding the last test report to the “reports”-beliefset. The reason is that the Test capability will immediately notice when the declared number of test cases has been executed and will subsequently send back the test results to the test center and terminate the test agent.