May 12, 2020

Returning the Target Application to the Base State

by Brian


The ‘start’ and ‘finish’ phases are essential components of an automated testing project. The ‘start’ phase defines what occurs before a test is run. The finish phase defines what occurs after.

AscentialTest is designed so that each test automatically has a start and finish phase. The start phase is mostly generated for the user through the App State wizards. The finish phase is left to the user. Recently we’ve discovered that many users are unaware of mechanics of the finish phase, so we decided to communicate best practices around the topic. This paper explains our intentions in designing the ‘Test’ class and how we envision the ‘OnFinish’ to be configured.

The Test Class

Every test created in AscentialTest derives from a class called ‘Test’ as shown below:

Returning the Target Application to the Base State


Because the ‘Test’ class is pretty much invisible, we all tend to take it for granted. When we click on the ‘Run’ icon in AscentialTest, we expect a test to run and it does because of the ‘Run’ method that is built into the class. But it isn’t just the body of the test that is being run. Every time a test is executed, the start and finish actions are also run.

Here is a brief explanation: When a test is executed in AscentialTest, the ‘Run’ method is called. The ‘Run’ method starts a timer and then calls another built-in method called ‘OnStart’. Most users are familiar with ‘OnStart’ because it is automatically generated by the App State wizards. In most cases, ‘OnStart’ includes the actions that launch and, if applicable, log in to the target application. Next the ‘Main’ gets called. The ‘Main’ includes all the steps and actions that make up the body of the test:

Returning the Target Application to the Base State


If an exception is raised during the ‘Main’, another method called ‘OnException’ gets called. Its job is to report the exception to the Results Output. Whether or not there is an exception, the ‘OnFinish’ method finally gets called. We expect the user to configure ‘OnFinish’ to return the target application to a known state that we refer to as the ‘base state’. It’s typically the state of the application when it is first invoked, after any login has been completed.

‘OnFinish’ is accessed by using the dropdown located above the steps/actions area in the App State Editor:

Returning the Target Application to the Base State


By default, ‘OnFinish’ is empty. That’s because the actions to return an application to its base state vary widely from application to application. It is not something that Zeenyx can provide universally. However we can offer guidelines and provide a function to help get you started.


To ensure that tests run reliably, it’s important that they are independent of each other and that each test starts and stops at the base state as defined above. A well-designed test includes steps that return the target application to the ‘base state’, which usually entails closing dialogs that were opened during the test. When a test fails and an exception is raised, there is often a break in the flow of the test. Control is passed to ‘OnException’ to raise the error and the application is often left in a state where the current test transaction is incomplete. This is where ‘OnFinish’ is called upon to return the target application to the ‘base state’.

To make it easier for users to configure the ‘OnFinish’, we’ve created a new function called ‘CloseActiveWindows’ partially pictured below:

Returning the Target Application to the Base State


‘CloseActiveWindows’ checks the state of the target application to determine if the application’s main window is active. If any dialogs or windows are opened, it attempts to close them. The built-in ‘Close’ action is called for each active window found. ‘Close’ attempts to click on the CloseBox (The ‘X’ in the upper right corner of a dialog) if it exists. Otherwise it types the <ALT-F4> keys. If the window is not successfully closed, ‘CloseActiveWindows’ takes additional steps to attempt to close it.

A call to ‘CloseActiveWindows’ should be placed in the ‘OnFinish’ method of your App State as pictured below:

Returning the Target Application to the Base State


The first parameter is the App Object name of the target application’s main window. The second parameter specifies the number of attempts that should be made to attempt to close any active dialogs.

We recognize that many applications will require further action to return the target application to the ‘base state’. The recommended approach is to create a custom ‘Close’ action for each dialog or window that requires addition steps. If a ‘Close’ action is defined for an App Object, it is that custom action that will be called by ‘CloseActiveWindows’ instead of the built-in Close action. A simple ‘Close’ actions may require a click on an ‘OK’ button. A more complex ‘Close’ action might entail the actions required to complete the current transaction. The amount of ‘statefulness’ in a given application determines the complexity of the ‘Close’ actions that will be required.

If you are reading this document, chances are that you already have ‘CloseActiveWindows’ in your possession.  If you do not, please contact us at to obtain a copy. We are happy to discuss the finish phase requirements for your target application and will assist you with designing effective ‘Close’ methods.