Event handlers execute scripts when specific events occur (for example, before every test case is executed), which allows you to perform various tasks or modifications. Use event handlers for:

Filtering requests.
Working with tests.
Working with virtual APIs.
Working with security and load tests.

ReadyAPI allows you to add event handlers to custom scripts or attach them to related test run events in your projects.

Manage event handlers

To access events for managing, click on the ReadyAPI toolbar.

Click the image to enlarge it.

You can also open the Project menu and click Events. The Events window will appear.

In the Events window, you can add and remove event handlers and enter your scripts to use them.

Click the image to enlarge it.

Add an event handler

To add a new event handler:

Click on the toolbar. This will call the Create EventHandler dialog.
Select an event handler and click OK. For details, see Available Events.
Write a script to enable the event handler.
Click OK.

The added event handler is in the table at the top of the window. The table has the following columns:

Column	Description
Name	The name of the event handler.
Event	The event to be used to activate the matching handler.
Target	The filter used to limit the number of test items the filter is applied to. Supports regular expressions and property expansions. For details, see Filtering Events.
Disabled	If selected, the event is disabled and will not trigger.

Delete an event handler

To remove an event handler, select it in the table and click .

Enable an event handler

To enable the added event handler, you need to write a script. You can use the Code Completion list to access the available objects, methods, and properties. To invoke the list, select Edit > Code Completion, or press Ctrl+Space.

For example, you need to change all 555 to 444 in all response messages. To do this, you should use the RequestFilter.afterRequest event handler and add a script:

Groovy

if( request.response == null )
return

// Get the response content
def content = context.httpResponse.responseContent

// Change the content
content = content.replaceAll( "555", "444" )

// Return the content
context.httpResponse.responseContent = content

Note:

The script debugger does not work for event handlers.

List of events

When you add a new event handler, ReadyAPI shows you the events to handle in the Create EventHandler dialog.

The following events are available:

Event Method Description

RequestFilter filterRequest Triggers prior to the request being sent, but after the request is created.

afterRequest Triggers after the request is sent.

TestSuiteRunListener beforeTestCase Triggers before the test case is called.

afterRun Triggers after the test suite is executed.

afterTestCase Triggers after the test case execution is over and the test case is closed.

beforeRun Triggers before the test suite is executed.

ProjectRunListener afterRun Triggers after the project is executed.

beforeRun Triggers before the project is executed.

afterTestSuite Triggers after the test suite is executed.

beforeTestSuite Triggers before the test suite is executed.

MockRunListener onMockRequest Triggers when the virtual service receives a request.

onMockRunnerStart Triggers when you start the virtual service.

onMockResult Triggers when the virtual service sends a response.

onMockRunnerStop Triggers when you stop the virtual service.

The MockRunListener.onMockRequest, MockRunListener.onMockRunnerStart, MockRunListener.onMockResult, and MockRunListener.onMockRunnerStop events are not triggered for JMS virtual services. Use the JMS-specific JmsMockRunListener events instead.

beforeRoute Triggers before a virtual service routes an incoming request to another API.

afterRoute Triggers after a virtual service receives a response to a routed request.

JmsMockRunListener onMockRequest Triggers when the JMS virtual service receives a request.

onMockRunnerStart Triggers when you start the JMS virtual service.

onMockResult Triggers when the JMS virtual service sends a response.

onMockRunnerStop Triggers when you stop the JMS virtual service.

SubmitListener beforeSubmit Triggers before the request is sent or created.

afterSubmit Triggers after the request is sent.

TestRunListener beforeRun Triggers before a test case starts running.

beforeStep Triggers before each test step in a test case is executed.

afterStep Triggers after each test step in a test case is executed.

afterRun Triggers after the test case run is complete.

Note: TestRunListener events trigger only when you run a test case. They are not triggered when you run a separate test step.

MonitorListener onMessageExchange Triggers when the built-in HTTP monitor of ReadyAPI detects a request has been sent and a response has been received.

onRequest Triggers when the HTTP monitor detects an incoming message.

beforeProxy Triggers before the request passes the HTTP monitor proxy.

afterProxy Triggers after the request passes the HTTP monitor proxy.

SecurityTestRunListener beforeSecurityScan Triggers before the security scan starts.

afterSecurityScanRequest Triggers after the security test sends a request.

afterSecurityScan Triggers after the security scan is finished.

beforeRun Triggers before the security test is run.

beforeStep Triggers before every test step run in the underlying test case is finished.

afterStep Triggers after every test step run in the underlying test case is finished.

afterRun Triggers after the security test ends.

afterOriginalStep Triggers after the targeted test step run is finished.

LoadTestRunListener afterLoadTest Triggers after the load test run is finished.

beforeTestStep Triggers before execution of each test step in the underlying test case.

loadTestStopped Triggers when you stop the load test.

afterTestStep Triggers after execution of each test step in the underlying test case.

beforeTestCase Triggers before the underlying test case is run.

loadTestStarted Triggers when the load test starts.

afterTestCase Triggers after the underlying test case run is complete.

beforeLoadTest Triggers before the load test is run.

Triggering order

The subsections below demonstrate the triggering order of the event handlers for the REST Sample Project, with the GET request only enabled. This is not actual code but just a description of the triggering order.

Functional test

// Project launch
ProjectRunListener.beforeRun
Project level setup script

  // Preparing to run the test suite
  ProjectRunListener.beforeTestSuite
  TestSuiteRunListener.beforeRun
  Test suite level setup script
  // Test suite launch

    // Preparing to run the test case
    TestSuiteRunListener.beforeTestCase
    TestRunListener.beforeRun
    Test case level setup script
    // Test case launch

      // The Start Virt Service test step
      TestRunListener.beforeStep
      MockRunListener.OnMockRunnerStart
      TestRunListener.afterStep

      // The View Form REST Request test step
      TestRunListener.beforeStep
      SubmitListener.beforeSubmit
      RequestFilter.filterRequest
      MockRunListener.OnMockRequest // The request is sent to the virtual API, so the OnMockRequest event triggers
      RequestFilter.afterRequest
      SumbitListener.afterSumbit
      TestRunListener.afterStep

      // The Stop Virt Service test step
      TestRunListener.beforeStep
      MockRunListener.OnMockRunnerStop
      TestRunListener.afterStep

    // Stopping the test case
    Test case level teardown script
    TestRunListener.afterRun
    TestSuiteRunListener.afterTestCase

  // Stopping the test suite
  Test suite level teardown script
  TestSuiteRunListener.afterRun
  ProjectRunListener.afterTestSuite

// Stopping the project
Project level teardown script
ProjectRunListener.afterRun

Security test

The following example uses the security test that contains a single Boundary scan.

// Security test launch
TestRunListener.before Run
Test case level setup script
// Launching the test case

  The Start Virt Service test step
  TestRunListener.beforeStep
  MockRunListener.OnMockRunnerStart
  SecurityTestRunListener.afterOriginalStep
  SecurityTestRunListener.beforeStep
  SecurityTestRunListener.afterStep

  // The View Form REST Request test step
  TestRunListener.beforeStep
  SubmitListener.beforeSubmit
  RequestFilter.filterRequest
  MockRunListener.OnMockRequest // The request is sent to the virtual API, so the OnMockRequest event triggers
  RequestFilter.afterRequest
  SubmitListener.afterSubmit
  SecurityTestRunListener.afterOriginalStep
  SecurityTestRunListener.beforeStep
  SecurityTestRunListener.beforeSecurityScan
  SecurityTestRunListener.afterSecurityScan  SecurityTestRunListener.afterStep

  // The Stop Virt Service test step
  TestRunListener.beforeStep
  MockRunListener.OnMockRunnerStop
  SecurityTestRunListener.afterOriginalStep
  SecurityTestRunListener.beforeStep
  SecurityTestRunListener.afterStep

Test case level teardown script
TestRunListener.afterRun
SecurityTestRunListener.afterRun

Performance test

The following example uses the basic load test, with a single virtual user active at a time.

// Load test launch
LoadTestRunListener.beforeLoadTest
LoadTestRunListener.loadTestStarted
TestRunListener.BeforeRun

  // Preparing to launch the test case
  LoadTestRunListener.beforeTestCase

// Test case contents repeat for each individual virtual user and subsequent requests:

  Test case level setup script
  // Test case launch

    The Start Virt Service test step
    TestRunListener.beforeStep
    LoadTestRunListener.beforeTestStep
    MockRunListener.OnMockRunnerStart
    TestRunListener.afterStep
    LoadTestRunListener.afterTestStep

    // The View Form REST Request test step
    TestRunListener.beforeStep
    LoadTestRunListener.beforeTestStep
    SubmitListener.beforeSubmit
    RequestFilter.filterRequest
    MockRunListener.OnMockRequest // The request is sent to the virtual API, so the OnMockRequest event triggers
    RequestFilter.afterRequest
    SumbitListener.afterSumbit
    TestRunListener.afterStep
    LoadTestRunListener.afterTestStep

    // The Stop Virt Service test step
    TestRunListener.beforeStep
    LoadTestRunListener.beforeTestStep
    MockRunListener.OnMockRunnerStop
    TestRunListener.afterStep
    LoadTestRunListener.afterTestStep

  // Stopping the test case
  Test case level teardown script
  TestRunListener.afterRun
  LoadTestRunListener.afterTestCase

// End of repeating contents

// Stopping the load test
LoadTestRunListener.loadTestStopped
LoadTestRunListener.afterLoadTest

Filter events

Use the Target column to apply an event only to specific test items. You can use regular expressions in this field. For example, you can limit the LoadTestRunListener.afterTestStep event handler to target only specific requests:

Enter Request1 so that the event is applied only to test items with the Request1 name.
Enter RegexRequest.* so that the event is applied only to test items that start with RegexRequest.
Use property expansions to get a value and compare it with the expected value. Enter ${=testStepResult.timeTaken > 50} in order for the event to trigger only if a request took less than 50ms to execute. If the comparison fails, the event will not trigger.

Handling Events