Katalon Keyword-Driven Testing: How It Works and When to Use It

Katalon Keyword-Driven Testing: How It Works and When to Use It

Keyword-driven testing is one of those testing methodologies that sounds abstract until you see it in practice — and then it makes immediate sense. Instead of writing test logic directly in code, you define a library of reusable actions ("keywords"), then build test cases by sequencing those actions. Non-technical team members can write and maintain tests; engineers build and maintain the keyword library.

Katalon Studio is built around keyword-driven testing at its core. Understanding how it works explains most of what makes Katalon different from a raw Selenium or Playwright setup.

What Is Keyword-Driven Testing?

In a keyword-driven framework, test cases are written in a tabular format:

Keyword Object Value
Open Browser https://app.example.com
Click btn_login
Type input_email user@example.com
Type input_password password123
Click btn_submit
Verify Element Present div_dashboard

Each row is a step. The keyword defines the action. The object identifies what to act on. The value provides input data.

The person writing the test doesn't need to know Selenium, WebDriver, or locator strategies. They use the keyword vocabulary. Engineers define what each keyword does in code, once.

Katalon's Built-In Keyword Library

Katalon ships with ~150+ built-in keywords covering web, API, mobile, and desktop testing. They're organized by category:

Web UI Keywords

The most commonly used:

Click — Clicks on a web element.

Click | Object Repository/Page_Login/btn_submit

Type — Types text into an input field (clears existing content first).

Type | Object Repository/Page_Login/input_email | user@example.com

Verify Element Present — Asserts that an element exists in the DOM.

Verify Element Present | Object Repository/Page_Dashboard/div_welcome

Verify Element Text — Asserts the text content of an element.

Verify Element Text | Object Repository/Page_Dashboard/h1_title | "Welcome back"

Select Option By Label — Selects a dropdown option by its visible text.

Select Option By Label | Object Repository/Page_Form/select_country | "United States"

Wait For Element Visible — Waits up to a timeout for an element to appear.

Wait For Element Visible | Object Repository/Page_Dashboard/div_content | 10

API Keywords

Send Request — Sends an HTTP request and stores the response.

def response = WS.sendRequest(findTestObject('REST_API/POST_login'))

Verify Response Status Code — Checks the HTTP status code.

WS.verifyResponseStatusCode(response, 200)

Verify Element Property Value — Validates a field in the response JSON/XML.

WS.verifyElementPropertyValue(response, 'data.userId', '12345')

Mobile Keywords

Start Application — Launches the mobile app. Tap — Taps a mobile element. Swipe — Swipes in a direction (left/right/up/down). Verify Element Text — Same concept as web, applied to mobile elements.

Custom Keywords

Built-in keywords cover common actions. Custom keywords extend the library with your own reusable logic.

Creating a Custom Keyword

In Katalon Studio: File → New → Keyword

This creates a Groovy file in the Keywords folder. Example:

package com.mycompany.keywords

import com.kms.katalon.core.annotation.Keyword
import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI

class LoginKeywords {

    @Keyword
    def loginWithCredentials(String email, String password) {
        WebUI.navigateToUrl('https://app.example.com/login')
        WebUI.setText(findTestObject('Page_Login/input_email'), email)
        WebUI.setText(findTestObject('Page_Login/input_password'), password)
        WebUI.click(findTestObject('Page_Login/btn_submit'))
        WebUI.waitForElementVisible(findTestObject('Page_Dashboard/div_welcome'), 10)
    }

    @Keyword
    def logout() {
        WebUI.click(findTestObject('Page_Header/btn_user_menu'))
        WebUI.click(findTestObject('Page_Header/btn_logout'))
        WebUI.waitForElementVisible(findTestObject('Page_Login/input_email'), 10)
    }
}

Once defined, these custom keywords appear in the manual test case editor alongside built-in keywords. A QA analyst can now write:

Keyword Value 1 Value 2
loginWithCredentials admin@example.com password123
(verify some post-login state)
logout

Keyword Best Practices

Keep keywords at the right abstraction level. A keyword like loginWithCredentials is well-scoped. A keyword like doEverythingForCheckout is too broad — it becomes a maintenance problem.

Keywords should be idempotent where possible. A navigateToProductPage keyword that always navigates fresh (rather than assuming you're already there) is more reliable in parallel execution.

Return values when useful. Custom keywords can return values — use this for things like getAuthToken() or createTestUser() that generate data you'll use in subsequent steps.

Log meaningful messages. Katalon's log viewer shows keyword execution. Adding KeywordUtil.logInfo("Logging in as: ${email}") makes debugging much faster.

Data-Driven Testing with Keywords

Keyword-driven and data-driven testing combine naturally in Katalon. You define the test logic once (via keywords), then run it against multiple data inputs.

Using Test Data Files

Create a data file: File → New → Test Data

Katalon supports:

  • Excel (.xlsx)
  • CSV
  • Database (via JDBC)
  • Internal data (defined directly in Katalon)

Example CSV (test-users.csv):

email,password,expected_role
admin@example.com,adminpass,Administrator
user@example.com,userpass,Member
readonly@example.com,readpass,Viewer

Binding Data to a Test Suite

In a Test Suite, configure Data Binding:

  1. Add your test case to the suite
  2. Click Show Data Binding
  3. Link each variable to the corresponding column in your data file
  4. Set iteration to run all rows

Katalon will execute the test once per row, substituting the bound values.

Using Data in Test Cases

Within a test case (script mode), access bound data via variables:

// Variables are passed from the test suite data binding
// email, password, expected_role are available as test case variables

WebUI.navigateToUrl('https://app.example.com/login')
WebUI.setText(findTestObject('Page_Login/input_email'), email)
WebUI.setText(findTestObject('Page_Login/input_password'), password)
WebUI.click(findTestObject('Page_Login/btn_submit'))

// Verify the role-specific UI element is visible
WebUI.verifyElementVisible(findTestObject("Page_Dashboard/label_role_${expected_role}"))

The Object Repository

Keywords operate on test objects — UI element definitions stored in the Object Repository. Each object stores locator strategies (XPath, CSS, ID, etc.) for finding elements.

This separation is important: when a developer renames a CSS class, you update the object in one place, and every keyword that references it gets the fix automatically. Without an Object Repository, you'd hunt through test scripts to find every affected locator.

Object Properties

Each object can store multiple locator strategies with priority ranking:

Priority 1: id = "btn-login"        (most stable, use first)
Priority 2: css = ".login-button"   (fallback)
Priority 3: xpath = "//button[text()='Log In']" (last resort)

Katalon tries locators in priority order at runtime. If the element's ID changes, it falls back to CSS. This is a basic form of resilience without needing a full self-healing solution.

Smart XPath

Katalon's object spy generates XPath automatically when you capture elements. The quality of generated XPath varies — for well-structured HTML, it's usually fine. For dynamically generated UIs, you'll often need to manually edit the XPath to remove brittle position-based expressions.

When Keyword-Driven Testing Makes Sense

Use it when:

  • Your team includes non-engineers who write or review tests
  • You're maintaining a large regression suite with many similar flows
  • You want to separate test logic (what to test) from implementation (how to test it)
  • Your business analysts need to verify test coverage maps to requirements

Don't use it when:

  • All your testers are engineers comfortable with code
  • You need fine-grained control over async behavior (Playwright's async model handles this better)
  • Your tests are highly exploratory or procedurally complex
  • You're building tests for a rapidly changing UI where keywords need constant updates

Keyword-driven testing trades some flexibility for maintainability and accessibility. It's the right trade-off for certain team compositions, not all of them.

Keyword-Driven vs. Script Mode

Katalon's dual-mode editor lets you switch between keyword/manual view and Groovy script view for the same test. They're two representations of the same underlying data.

In practice, most experienced automation engineers work primarily in script mode — it's faster to write and more expressive. The keyword mode is most valuable for:

  • Onboarding new team members
  • Writing acceptance criteria in test form with business stakeholders
  • Capturing initial test flows via recording, then refining in script mode

Don't treat keyword mode as "simple" and script mode as "real." They serve different purposes and work best in combination.


Building a keyword-driven framework from scratch requires significant setup. HelpMeTest offers AI-powered test automation where you write tests in plain English — similar accessibility to keyword-driven testing, without the framework overhead.

Read more

Start now free