Handling Events

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.

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.

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:

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.
RequestFilter	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.
	Important 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.
SubmitListener	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.afterRunSecurityTestRunListener.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

Manage event handlers

Add an event handler

Delete an event handler

Enable an event handler

Note

List of events

Important

Note

Triggering order

Functional test

Security test

Performance test

Filter events

See Also

Search results