Running Parallel Windows Desktop Automation on Self-Hosted Runners via GitHub Actions

Tips and Tricks
, , ,
1

Problem

Testing Windows Desktop Applications presents a unique constraint: often, the application logic allows only one instance to run on a machine at a time. This makes parallel testing on a single machine impossible.

To scale automation and reduce execution time, teams need to distribute tests across multiple remote Windows machines simultaneously. However, coordinating these distributed runs via a CI/CD pipeline (like GitHub Actions) and managing the necessary drivers (WinAppDriver) can be complex depending on the Katalon version.

Solution

The solution is to use GitHub Actions Self-Hosted Runners installed on multiple remote Windows servers.

By defining a Matrix Strategy in your GitHub Actions workflow, you can trigger a single pipeline that automatically distributes the test suite execution across your available Windows agents. Each runner picks up a job and executes it locally, creating physically isolated environments for your application.

How to

Step 1: Set Up Self-Hosted Runners

  1. Provision Servers: Prepare your remote Windows Servers (e.g., Server A, Server B).
  2. Install Dependencies (Version Dependent):
  • For KRE v9.x: You must manually install and configure Windows Application Driver (WinAppDriver) on each machine. Ensure it is running and listening on the default port (typically 4723) before tests begin.
  • For KRE v10.x: No separate action is needed. The dependency handling for WinAppDriver is streamlined within the engine, removing the need for manual installation.
  1. Install Software: Install Katalon Runtime Engine (KRE) and your target Desktop Application on all machines.
  2. Register Runner:
  • Go to GitHub Repository > Settings > Actions > Runners.
  • Download and run the registration agent on each Windows server.
  • Crucial: Assign a custom label (e.g., windows-desktop-agent) to these runners to target them in your workflow.

Step 2: Configure the GitHub Workflow

Create a .yml file in .github/workflows. Use the matrix strategy to split your tests and target the custom label.

name: Distributed Desktop Automation

on:
  schedule:
    - cron: '0 2 * * *' # Daily at 2 AM
  workflow_dispatch: # Manual trigger

jobs:
  desktop-test-execution:
    # Target your specific self-hosted Windows agents
    runs-on: [self-hosted, Windows]
    
    strategy:
      fail-fast: false
      matrix:
        # Define the test suites to run in parallel
        testSuite: 
          - 'Test Suites/Login_Module'
          - 'Test Suites/Order_Module'
          - 'Test Suites/Inventory_Module'

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Execute Katalon Desktop Tests
        uses: katalon-studio/katalon-studio-github-action@v4
        with:
          version: '10.0.1' # Using v10 removes the need for manual WinAppDriver setup
          projectPath: '${{ github.workspace }}'
          args: >-
            -retry=0
            -testSuitePath="${{ matrix.testSuite }}"
            -browserType="Desktop"
            -apiKey="${{ secrets.KATALON_API_KEY }}"

Step 3: Execution Logic

  • When triggered, GitHub creates 3 separate jobs.
  • Your pool of self-hosted runners picks them up.
  • Because KRE v10 is used in the example, the runners execute immediately without checking for a manually running WinAppDriver instance.

Outcome

  • Simplified Infrastructure (v10+): Upgrading to KRE v10 removes the maintenance overhead of managing WinAppDriver.exe processes on your build agents.
  • True Parallelism: You can run multiple desktop tests at once without application instance conflicts.
  • Scalability: To speed up testing, simply provision another Windows Server, install the GitHub agent, and join the pool.
2

Hope this saves someone a debugging hour :folded_hands:

I share more real-world Katalon patterns I run into while supporting customers on the academy — you can browse my profile here if you’d like to read more: Meet the contributor: Phuc Truong

If you’ve hit a variant of this or solved it differently in your environment, drop a reply — always interested to hear how other teams handled it.

3

Thanks for nice share

4

Wow nice sharing

5

Excellent walkthrough. Running Windows desktop automation in parallel on self-hosted GitHub Actions runners is a powerful way to improve execution speed and make better use of available hardware resources. What I particularly like is how this approach bridges the gap between traditional desktop automation and modern CI/CD practices.

This topic deserves more attention on YouTube because many automation engineers and developers still rely on sequential execution without realizing how much time can be saved through parallelization. A follow-up video showing real-world performance comparisons, resource management strategies, and scaling multiple runners would be incredibly valuable for anyone building large automation pipelines. Thanks for sharing such a practical and forward-thinking solution.