12.2 Managing Synthetic Tests with Scripts

The Experience Manager Monitor scripting layer includes a testEngine object that allows user-defined scripts to monitor and influence the operation of the monitor’s synthetic test engine. The testEngine object includes methods that allow scripts to retrieve information about deployed tests and to change the run status of any deployed test or test scenario. It also defines fields (JavaScript properties) in which a script can define handlers to monitor changes in the test configuration, and the results of test and scenario execution. For a complete description of the testEngine object, see Section A.1.3, The “testEngine” object.

As an example, suppose we had a test called 'WebTest' that monitored a Web site and another test called 'Diagnostics' that diagnosed potential causes in the event 'WebTest' had errors. We only want 'Diagnostics' to run if 'WebTest' fails. To implement this logic, we should create a Javascript function that implements the basic logic by processing a SyntheticTestResults object. For information about the SyntheticTestResults object, see Section A.2.18, SyntheticTestResults).

function myHandler(testResult)
{
   if(testResult.test.name.equals('WebTest'))
   {
      if(testResult.getFailCount() > 0)
      {
          testEngine.activateTest('Diagnostics');
      }
   }
}

Then we should designate myHandler as the listener for the OnTestComplete event:

testEngine.onTestComplete=myHandler;

When this script is loaded as the test management script, the 'Diagnostics' test is started after the first failure of 'WebTest'. However, the example is not complete. As it is scripted, 'Diagnostics' runs continually after it is activated. What we really want is for it to run only once after a failure of 'Web Test'. To fix this, we will extend 'myHandler' to also look for testResults from our 'Diagnostics' test:

testEngine.onTestComplete=myHandler;
function myHandler(testResult)
{
   if(testResult.test.name.equals('WebTest'))
   {
      if(testResult.getFailCount() > 0)
      {
          testEngine.activateTest('Diagnostics');
      }
   }
   else if(testResult.test.name.equals('Diagnostics'))
   {
      testEngine.deactivateTest('Diagnostics');
   }
}

To deploy a test management script, both the script file and an associated properties file are required. The properties file specifies the name of the script file, as well as any configuration parameters needed by the script. The example script from above does not use any configuration parameters, but it certainly is more flexible if the names of the tests 'Web Test' and 'Diagnostics' could be changed without editing the script itself. To do this, we would change the hard-coded with variables that are loaded with values set in the test management properties file:

var monitoredTestName=testEngine.properties.get('example.monitorTestName',null);
var diagnosticTestName=
    testEngine.properties.get('example.diagnosticTestName',null);

if(monitoredTestName != null && diagnosticTestName != null)
{
   testEngine.onTestComplete=myHandler;
}

function myHandler(testResult)
{
   if(testResult.test.name.equals(monitoredTestName))
   {
      if(testResult.getFailCount() > 0)
      {
          testEngine.activateTest(diagnosticTestName);
      }
   }
   else if(testResult.test.name.equals(diagnosticTestName))
   {
      testEngine.deactivateTest(diagnosticTestName);
   }
}

The name of the test to monitor and the diagnostics test are loaded from properties example.monitorTestName and example.diagnosticTestName respectively. In addition, we added logic so that if either of these properties is not set, the event handler is not configured.

To deploy this management script, we should save the script to a file called example.js in the monitor’s scripts directory, then we should create the properties file example.properties in the /config directory. Following is the content of example.properties:

tests.management.script=example.js
example.monitorTestName=WebTest
example.diagnosticTestName=Diagnostics

Finally, we must tell the monitor that we want to use this test management configuration. To do that, update monitor.properties as follows:

tests.management.properties=example.properties

You must then restart the monitor for these changes to take effect.

That covers the basics of how to manage synthetic tests with scripts. The example we used is fairly simple, but covers the core concepts. A slightly more sophisticated example is included with the monitor install called 'FailOverDemo'. In that example, we extend the basic concepts shown here by allowing multiple tests to be monitored, each with a unique configuration. While the script and its properties are more complex, the sophistication comes from more advanced Javascript. It uses the same basic hooks shown here.