Skip to main content

Introduction to custom keywords in Katalon Studio

Important:
  • You have a Katalon Studio Enterprise license.

In addition to built-in keywords, you can define custom keywords to extend the capabilities of Katalon Studio. Once created, custom keywords can be used when executing test cases like other built-in keywords.

Create a keyword package

A package is a namespace that organizes a set of related classes and interfaces.

You can keep things organized by grouping related classes and interfaces into packages.

To create a keyword package, do as follows:

  1. From Tests Explorer, right-click Keywords folder and select New > Package.
    Right-click Keywords folder and create new package
    The New Keyword Package dialog is displayed.

    The New keyword package appears

  2. Enter a name for your package, then click OK.

In the Tests Explorer section, a new package is created accordingly.The new keyword package in the Tests Explorer sidebar

Create a custom keyword

To create a custom keyword, do as follows:
  1. From Tests Explorer, right-click Keywords folder and select New > Keyword.
    Right-click Keywords folder and create new keyword
    The New Keyword dialog is displayed.

    The New keyword dialog appears

  2. Enter a class name and specify a package for the keyword. Click OK.
    By default, a class name cannot start with a number, contain spaces, or have special characters. You can follow the Java naming convention: start with a lowercase letter, then capitalize the first letter of every following word (for example, newCustomKeyword).
    Note:

    A new custom keyword is created under the specified package.The new custom keyword in the Tests Explorer sidebar

  3. Enter the following code snippet in your class to define a custom keyword:
    @Keyword (keywordObject = "<category_name>")
    def keywordName(parameters…) {
    // enter your code here
    // you can use either Groovy or Java
    }
    ItemDescriptionRequired
    @KeywordThe annotation to indicate that the block of code below is the definition of a keyword.Yes
    keywordObjectThe category of your custom keyword.No
    keywordNameThe name for your custom keyword.Yes
    parametersThe list of parameters to be used in the custom keyword.No
    For example:

    An example of custom keyword definition

    From version 7.5.5 and later, Custom Keywords in Keywords Browser are put in alphabetical order, and you can categorize them. The category name should be declared via keywordObject with the same mechanism as the built-in keywords.

    The sample below describes a keyword with the "Browser" category:
    @Keyword(keywordObject = "Browser")
    def refreshBrowser() {
    }
    In the Keywords Browser:

    Custom keyword in Keywords Brower view

  4. When you are done, save the keyword file.

Use custom keywords in the manual view

To use your defined custom keywords in the manual view of a test case, do as follows:
  1. Open a test case in the manual view. Select Add > Custom Keyword.
    Select Add > Custom keyword in manual view
  2. A new test step is added. Select your preferred custom keyword.
    Browse custom keyword
Your custom keyword is added as a test step.The custom keyword appears as a test step in manual view

Use custom keywords in the script view

To use your defined custom keywords in the script view of a test case, do as follows:
  1. The Class CustomKeywords of Katalon Studio allows you to access all custom keywords. Enter the following syntax into the script editor:
    CustomKeywords.
  2. After you type the dot character, the Content Assist function is invoked. All the custom keywords defined in your test project are displayed as below:
    A list of custom keywords displayed when Content Assist is invoked
  3. Select your custom keyword and provide all parameters as required.
You've added your custom keyword in the script view.

Work with custom keywords

The following classes and methods can be useful when working with custom keywords.

ClassMethodDescription
DriverFactorygetWebDriver()Get the currently active web driver.
Test ObjectaddProperty(String name, ConditionType condition, String value)Add a new property to the test object.
setProperties(List<TestObjectProperty> properties)Set the properties of the test object.
getObjectId()Get object ID.
findPropertyValue(String name, boolean caseSensitive)Find the value of a property using the property name.
Keyword UtillogInfo(String message)Log the message as info.
markError(String message)Mark a keyword to be an error.
markErrorAndStop(String message)Mark a keyword to be an error and stop execution.
markFailed(String message)Mark a keyword to be failed and continue execution.
markFailedAndStop(String message)Mark a keyword to be failed and stop execution.
markPassed(String message)Mark a keyword to be passed.
markWarning(String message)Mark a keyword to be a warning.