Test Fixtures and Test Listeners (Test Hooks) in Katalon Studio

To extend your current testing flow, the test fixtures (@setUp/@tearDown methods) and test listeners might be useful for prerequisite and clean-up configurations for all the tests.

With the prerequisite configuration, the test engine must take specific actions before starting test execution. For clean-up configuration, the test engine must carry out some actions after the test execution finishes.

The infographic below visualizes how Katalon Studio executes your automated test projects with the test fixtures and test listeners methods.

Note:

• Test listeners are always triggered first if you define both test listeners and activate setUp/tearDown methods simultaneously.

This document guides you through how to configure the setUp/tearDown methods and the test listeners in Katalon Studio.

setUp() and tearDown() for test suite and test case

In Katalon Studio, you can specify prerequisite and clean-up configurations for your test cases using the @setUp and @tearDown methods.

Here are some common usages of the @setUp and @tearDown methods:

Method	Common usage
@setUp	Prepare a testing environment, such as: Starting new browser with clean cookies. Creating temporary and proxy databases, directories. Starting a server process. Call required test cases for the executed test suite.
@tearDown	Clean-up testing environment, such as: Closing connections to browsers. Disconnecting from databases or server. Call tearDown test cases for the executed test suite.

The table below describes the trigger conditions of these methods:

Method	Description	Trigger Condition
@setUp	Setup test suite environment.	Before executed test suites.
@setUpTestCase	Run before each test case starts.	Before executed test cases.
@tearDown	Clean test suites environment.	After executed test suites.
@tearDownTestCase	Run after each test case ends.	After executed test cases.

Activate setUp and tearDown in a test suite

In the test suite editor, switch to the Script tab to view the setUp and tearDown methods template.

By default, the setUp and tearDown methods are not triggered even if they match with provided trigger condition as shown in the below code sample:

/**
 * Setup test suite environment.
 */
@SetUp(skipped = true) // Please change skipped to be false to activate this method.
def setUp() {
	// Put your code here.
}

To activate the @setUp and @tearDown methods, you need to set the skipped value to false. For example:

@SetUp(skipped = false)

Note:

• Executing with the setUp/tearDown methods still generates execution logs as usual.

• You cannot see setUp and tearDown executed reports from generated Test Suite report. You can only see setUpTestCase and tearDownTestCase in generated Test Suite report.

  

Add setUp and tearDown in manual view of a test case

In the manual view of a test case, you can add the setUp and tearDown method by following these steps:

1. Click on the drop-down button of the Add icon and choose Method. To learn more about the method statement, see Define Method.
   The Method builder dialog appears.
2. Enter your method's name and its return value, then choose one of the options below:
   

   Method	Description
   Set Up	This method is always called first, before executing the main test steps.
   Tear Down If Failed	This method is called after executing all steps of the test case, if one of those steps is marked as Failed.
   Tear Down If Passed	This method is called after executing all steps of the test case, if all of those steps are marked as Pass.
   Tear Down If Error	This method is called after executing all the test case steps, if one of those steps is marked as Error.
   Tear Down	This method is called at the end of an execution.

3. To add a test step under a method, choose the line of that method, then click Add.
   A new keyword is added under that method.

   

   Note:

   • The setUp/tearDown methods might be marked as Error if any issue occurs during their execution. The possible exception is when the AssertionError class is used, or if the methods are skipped.

Add setUp and tearDown in the script view of a test case

In the script view of a test case, you can declare a method as setUp/tearDown methods using the matching annotation above them. For example:

@com.kms.katalon.core.annotation.SetUp
def setup(def param1, def param2) {
}
@com.kms.katalon.core.annotation.TearDownIfFailed
def teardownIfFailed(def param1, def param2) {
}
@com.kms.katalon.core.annotation.TearDownIfPassed
def teardownIfPassed(def param1, def param2) {
}
@com.kms.katalon.core.annotation.TearDownIfError
def teardownIfError(def param1, def para2) {
}
@com.kms.katalon.core.annotation.TearDown
def teardown(def param1, def param2) {
}

Test Listeners (Test Hooks)

Test listeners are test steps created to "listen" to the event defined in the script and behave accordingly. In this section, you will learn how to create a test listener.

Create new Test Listeners

Test listeners are test artifacts. You can perform all basic operations such as create, copy/cut, rename, or delete with test listeners. To create a new test listener, do as follows:

1. In the Tests Explorer panel, right-click on Test Listeners. Select New > New Test Listener.
   
2. The New Test Listener dialog appears with four options as below:
   

   Option	Description
   Generate sample Before Test Case method	Create a sample test listener executed before every test case starts.
   Generate sample After Test Case method	Create a sample test listener executed after every test case ends.
   Generate sample Before Test Suite method	Create a sample test listener executed before every test suite starts.
   Generate sample After Test Suite method	Create a sample test listener executed after every test suite ends

   You can select one or multiple options, then click OK.
   Once finished, Katalon Studio generates a sample template accordingly. The template includes necessary annotations, libraries, and supported functions.

   Note:

   • You can create multiple test listeners.
   • If you have more than one test listener class, the classes themselves are instantiated in Katalon storage in alphabetical order. Only then are the individual listener methods executed top-down.
   • The execution status of any steps within test listeners does not affect the overall status of the executed test case. For example, if you have a FAILED output in any of your test listeners, but the final status of the executed test case is PASSED, then the test case status is PASSED.

   You can view the test listener template here:

   import internal.GlobalVariable as GlobalVariable
   
   import com.kms.katalon.core.annotation.BeforeTestCase
   import com.kms.katalon.core.annotation.BeforeTestSuite
   import com.kms.katalon.core.annotation.AfterTestCase
   import com.kms.katalon.core.annotation.AfterTestSuite
   import com.kms.katalon.core.context.TestCaseContext
   import com.kms.katalon.core.context.TestSuiteContext
   
   class NewTestListener {
   	/**
   	 * Executes before every test case starts.
   	 * @param testCaseContext related information of the executed test case.
   	 */
   	@BeforeTestCase
   	def sampleBeforeTestCase(TestCaseContext testCaseContext) {
   		println testCaseContext.getTestCaseId()
   		println testCaseContext.getTestCaseVariables()
   	}
   
   	/**
   	 * Executes after every test case ends.
   	 * @param testCaseContext related information of the executed test case.
   	 */
   	@AfterTestCase
   	def sampleAfterTestCase(TestCaseContext testCaseContext) {
   		println testCaseContext.getTestCaseId()
   		println testCaseContext.getTestCaseStatus()
   	}
   
   	/**
   	 * Executes before every test suite starts.
   	 * @param testSuiteContext: related information of the executed test suite.
   	 */
   	@BeforeTestSuite
   	def sampleBeforeTestSuite(TestSuiteContext testSuiteContext) {
   		println testSuiteContext.getTestSuiteId()
   	}
   	/**
   	 * Executes after every test suite ends.
   	 * @param testSuiteContext: related information of the executed test suite.
   	 */
   	@AfterTestSuite
   	def sampleAfterTestSuite(TestSuiteContext testSuiteContext) {
   		println testSuiteContext.getTestSuiteId()
   	}
   }

Example: Using test listeners

In this example, we define multiple environments as different global variables by using test listeners. For more information, see Global variables.

Before you execute your test case, change the environment variable to your preferred environment by following the script below:

import internal.GlobalVariable as GlobalVariable

import com.kms.katalon.core.annotation.BeforeTestCase
import com.kms.katalon.core.annotation.BeforeTestSuite
import com.kms.katalon.core.annotation.AfterTestCase
import com.kms.katalon.core.annotation.AfterTestSuite
import com.kms.katalon.core.context.TestCaseContext
import com.kms.katalon.core.context.TestSuiteContext

/**
 * Executes before every test case starts.
 * @param testCaseContext related information of the executed test case.
 */

@BeforeTestCase
def sampleBeforeTestCase(TestCaseContext testCaseContext) {
    if (GlobalVariable.gl_Environment == 'Local') {
        GlobalVariable.gl_Url = 'localhost'
    } else if (GlobalVariable.gl_Environment == 'Staging') {
        GlobalVariable.gl_Url = 'staging'
    }
}

Note:

• To learn more about test listeners, refer to chapter 2 of our Katalon Academy course: Test Listener.