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.
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. |
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. | |
ImportantThe | ||
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
| ||
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.