template.t Explained

The following line of code in Code for template.t is the first required line in a multi-application test case file. It is the test case declaration.

Note: The code does not pass an application state as in the stand-alone environment.
multitestcase MyTest (STRING sMach1, STRING sMach2)
In the multi-application environment the arguments to your test case are names of the machines to be tested; you specify application states inside the test case. You can code the machine names arguments as you like. For example, you can pass a file name as the only argument, and then, in the test case, read the names of the machines from that file. Or you can define a LIST OF HMACHINE data structure in your test plan, if you are using the test plan editor, to specify the required machines and pass the name of the list, when you invoke the test case from the test plan. This template assumes that you are using a test plan and that it passes the Agent names when it invokes the test case. For this example, the test plan might specify the following:
Mytest ("Client1", "Client2")
The next two code lines are the first required lines in the test case:
SetUpMachine (sMach1, MyFirstApp, "MyFirstAppState")
SetUpMachine (sMach2, My2ndApp, "My2ndAppState")

You must execute the SetUpMachine function for every client machine that will be tested. For each SetUpMachine call, you specify the application to be tested, by passing the name of the main window, and the state to which you want the application to be set, by passing the name of the application state if you have defined one.

The SetUpMachine function issues a Connect call for a machine you want to test and then configures either the base state or a specified application state.

It does this as follows:
  • It associates the client application’s main window name with the specified machine so that the DefaultBaseState function can subsequently retrieve it to set the base state.
  • It associates the name of the application’s base state, if one is specified, with the specified machine so that the SetMultiAppStates function can subsequently retrieve it and set the application to that state at the start of the test case.
The first argument for SetUpMachine is the machine name of one of your client machines. The second argument is the name you supply in your main window declaration in your test frame file, frame.inc. For this example, the frame.inc file specifies the following:
window MainWin MyFirstApp
Because this template specifies two different applications, it requires two different test frame files.
The third argument is the name you provide for your application state function in your appstate declaration for this test. For this example, the appstate declaration is the following:
appstate MyFirstAppState () based on MyFirstBaseState
The appstate declaration could also be of the form:
appstate MyFirstBaseState ()

Although the DefaultBaseState function is designed to handle most types of GUI-based applications, you may find that you need to define your own base state. It would be the application state that all your tests for this application use. In this case, you would still pass this application state to SetUpMachine so that your application would always be brought to this state at the start of each test case.

This template specifies two application states for generality. You would not use an application state if you wanted to start from the main window each time. If you have a number of tests that require you to bring the application to the same state, it saves test-case code to record the application state once, and pass its name to SetUpMachine. You will probably place your application state declarations in your test frame file.
SetMultiAppStates ()
The SetMultiAppStates function must always be called, even if the test case specifies no application state, because SetMultiAppStates calls the DefaultBaseState function in the absence of an appstate declaration. SetMultiAppStates uses the information that SetUpMachine associated with each connected machine to set potentially different application states or base states for each machine.
 spawn
  SetMachine (sMach1)
  // Here is placed code that drives test operations

The spawn statement starts an execution thread, in which each statement in the indented code block below it runs in parallel with all currently running threads. There is no requirement that your test case should drive all your test machines at the same time, however, this is usually the case. The SetMachine function directs 4Test to execute this thread’s code by means of the Agent on the specified machine. This thread can then go on to drive a portion, or all, of the test operations for this machine.

 spawn
  SetMachine (sMach2)
  // Here is placed code that drives test operations
rendezvous
// "..."
The second spawn statement starts the thread for the second machine in this template. The rendezvous statement blocks the execution of the calling thread until all threads spawned have completed. You can use the rendezvous statement to synchronize machines as necessary before continuing with the test case.