Zeenyx Academy

Returning the Target Application to the Base State

Print Friendly, PDF & Email


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:

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:

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:

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’ pictured below:

‘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:

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 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’ action 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 [email protected] 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.


Share the Post:

Related Content

Instructional Content, Thought Leadership

A Thousand G2 Reviews Later: Software Testing Tools Are Too Expensive

Instructional Content, Thought Leadership

Build Tests, Not Frameworks

Instructional Content

AscentialTest Error Tracking and Debugging

Instructional Content

Self-Guided PowerBuilder Tutorial

Get Started For Free: 30 Day Trial

Click here to download the Host ID generator. The download package includes full instructions. Please send us your details below to speed the process along.

Our Distribution and Consulting Partners



Loop Software


Matryxsoft Tech


OCS Consulting


What We Are Up To Next

TFS/Azure Integration

Check our new Azure extension for executing AscentialTest command lines in the Azure Marketplace.

We look forward to offering additional integration with Microsoft’s Team Foundation Server and Azure through defect tracking and version control soon.

Omnis Studio

Automated testing support for OMNIS Studio is coming soon. All OMNIS elements will be supported including complex grids, list boxes, tables and tree views.

Custom Objects

Add automated testing support easily for your custom application elements by responding to simple test API messages with json strings. This feature will open up the possibility of testing any GUI element and  will be offered free of charge.

Test Debugger

Set breakpoints in your automated tests, view global and local variables and execute statements to make it easier to debug tests running on any of our supported platforms.

Get a Competitive Quote

Thank you for submitting your inquiry!

We will get back to you ASAP.  We aim to respond to all inquiries within 24 hours.