on modal action
Specify the action to be invoked in the event of the appearance of a modal dialog box which would otherwise disrupt the intended flow of test automation.
(Optional) Name of the action to be executed upon the occurrence of a modal dialog box. (Learn more.)
If no action handler is defined, on modal action, by default, simply attempts to close the dialog.
This action may be used within the following project items: test modules and user-defined actions.
- The on modal action directive is triggered by the appearance of a modal dialog box which belongs to the same process as that of the window argument of the last interfacing action.
- Upon a TA Client-initiated execution of an on modal action action, its directive remains in effect until the end of the test run (or until another on modal action action is executed). This is true even in the case of a serial test run. However, when running a batch file, the on modal action directive remains in effect only until the end of the test module in which it appears.
- The on modal action directive is triggered by two conditions:
- the failure of TestArchitect automation to locate a given UI object in the course of executing a UI-interactive action (which, in the absence of an on modal action directive, would result in an automation error); and
- the presence of a modal dialog box.
- Upon triggering, the directive results in one of the following:
- execution of the handler action specified in the on modal action’s action argument, or
- a direct attempt to close the dialog box (which is the default, if no action argument is provided).
- In order to retrieve the definition of the current modal dialog box, use the get modal definition built-in action.
- When an on modal action directive is triggered, the handler action is invoked up to five (by default) times. (The number of actual retries is defined by the modal close attempt built-in setting.) Each time control returns from the handler action, TestArchitect attempts to resume normal automation starting with the last action executed prior to the invoking of the handler action. In the event that the dialog is not dismissed, or is immediately activated again by the re-execution of the action, up to <modal close attempts> calls to the handler action are made. After that, the on modal action directive is lifted (that is, no further calls to the handler are made), and any further automation errors generated by the triggering action are no longer suppressed.
- Execution of an on modal action causes any existing on modal action directive to be superseded. That is, at any given point in a test run, it is the handler action (or close directive) of the last executed on modal action action that will be triggered by the appearance of a qualifying modal dialog.
- This action supports the <ignore> modifier. If the string
<ignore>is present as the value of any of the arguments, or any argument contains an expression that evaluates to
<ignore>, the action is skipped during execution.
Use of this action is supported on the following systems/platforms:Windows.
Applicable Built-In Settings
The following settings are applicable to this action: remove double quotes from cells.
Scenario: You are aware of the fact that the AUT under development is, at times, capable of throwing unexpected exceptions, resulting in the appearance of modal dialogs. You wish to allow your test to handle such exceptions gracefully wherever they may occur, by dismissing the dialog, so that automation may continue. You also want to record the error message displayed by the dialog. Hence, you want the action lines handling this contingency to:
- capture screenshots when the modal dialog box unexpectedly appears, using the built-in capture screen action;
- click the Continue button, which such exception dialogs are always expected to have, to dismiss the dialog and allow automation to proceed; and
- Allow for the possibility that a modal dialog other than the standard “Unhandled exception” dialog has appeared, one that lacks a Continue button. Hence, if your procedure is unable to find a Continue button, simply attempt to close the modal dialog box with a built-in close window action.
At line #19 in the test procedure during the automated run, an unexpected modal dialog box appears. This triggers the modal dialog handler action to dismiss the dialog. Subsequently, TestArchitect resumes normal automation starting with the last action (line #19) executed prior to the invoking of the handler action.