Ranorex Tutorial: Automated GUI Testing for Desktop and Web Applications

Ranorex is a commercial test automation tool built for GUI testing across desktop (Windows, WinForms, WPF, UWP), web (Chrome, Firefox, Edge, Safari), and mobile (iOS, Android) applications. It combines a codeless recorder with a full C# scripting environment, making it accessible to both non-programmers and developers.

This tutorial covers the fundamentals: recording your first test, using the object repository, writing C# test code, and integrating Ranorex into CI/CD pipelines.

What Is Ranorex?

Ranorex consists of three main components:

1. Ranorex Studio — the IDE for creating, editing, and running tests. Windows-only.
2. Ranorex Recorder — captures user interactions and generates replay-ready tests
3. Ranorex Runtime — headless execution engine for CI/CD (no UI required)

Tests can be created via GUI recording, code-only, or a hybrid approach. All tests compile to .NET assemblies, which means they can run anywhere .NET runs.

What makes Ranorex different from Selenium:

• Works on native Windows applications (WinForms, WPF, UWP, Win32)
• Uses RanoreXPath for element identification instead of XPath/CSS selectors
• Handles native controls, menus, and dialogs that browsers don't expose
• Includes image-based recognition as a fallback
• Generates a visual report with screenshots automatically

Installation

Requirements:

• Windows 10 or 11
• .NET Framework 4.5+
• Visual Studio 2019 or 2022 (optional — Ranorex Studio is standalone)

Download and install Ranorex Studio from ranorex.com. A 30-day trial is available. After installation, open Ranorex Studio.

Creating Your First Test

New Solution Setup

1. Open Ranorex Studio
2. File → New Solution
3. Choose "Standard Suite" for a test project with a module structure
4. Name your solution and project

The solution structure:

MySolution/
├── TestSuite.rxtst          # Test suite definition
├── Recording1.rxrec         # Recorded test modules
├── Repository.rxrep         # Object repository
└── TestModule.cs            # Code module (if using C#)

Recording a Web Test

1. Click Record in Ranorex Studio
2. Ranorex prompts for a recording profile — choose Web Browser
3. Select the browser (Chrome, Firefox, or Edge)
4. Enter the start URL: https://example.com
5. Click Start Recording — a browser opens
6. Perform your test actions:
   • Click on elements
   • Type in text fields
   • Navigate pages
7. Add validation points: right-click an element → Add Validation
8. Click Stop in the recording toolbar

Ranorex generates a module (.rxrec) with all recorded actions.

Recording a Desktop Test

For Windows desktop applications:

1. Click Record → Choose Windows Application
2. Enter the application executable path or use the picker to click on a running app
3. Perform actions in the application — Ranorex captures clicks, keyboard input, window events
4. Add validations for expected values

The recording captures control types natively: Button, TextBox, ListView, TreeView, ComboBox — not generic HTML elements.

The Object Repository

The object repository is Ranorex's core concept. Instead of embedding element identifiers directly in test code, you reference them from a centralized repository.

RanoreXPath

Ranorex identifies elements using RanoreXPath — a path-based syntax similar to XPath but designed for both web and desktop:

Web element example:

/dom[@domain='example.com']//button[@id='submit-btn']

Desktop element example:

/win[@title='My Application']//button[@caption='OK']

Dynamic path (partial matching):

/dom[@domain='example.com']//input[contains(@id,'username')]

Managing the Repository

Elements recorded are automatically added to the repository. You can:

• Rename elements to meaningful names (e.g., LoginButton instead of btn_submit_1)
• Group elements by page/window into folders
• Edit the RanoreXPath if the element changes
• Set element visibility timeout per element

Repository/
├── LoginPage/
│   ├── UsernameField
│   ├── PasswordField
│   └── LoginButton
├── Dashboard/
│   ├── WelcomeMessage
│   └── NavigationMenu

Repository Best Practices

• Name elements by function, not technical attributes: SubmitOrderButton not button_id_42
• Group by page or feature for discoverability
• Avoid overly specific paths — they break when layout changes
• Use contains() for dynamic IDs — @id='user_12345' breaks; contains(@id,'user_') is resilient
• Review auto-generated paths — Ranorex sometimes creates brittle absolute paths; simplify them

Writing C# Test Code

Ranorex tests can extend beyond recording with full C# code. Create a code module:

1. Right-click project → Add → New Item → Code Module
2. Add the [TestModule] attribute

using Ranorex;
using Ranorex.Core;
using Ranorex.Core.Testing;

[TestModule("LoginTest", ModuleType.UserCode, 1)]
public class LoginTest : ITestModule
{
    // Bind to repository elements
    [RepositoryItem("LoginPage/UsernameField")]
    public TextField UsernameField { get; set; }
    
    [RepositoryItem("LoginPage/PasswordField")]
    public TextField PasswordField { get; set; }
    
    [RepositoryItem("LoginPage/LoginButton")]
    public Button LoginButton { get; set; }
    
    [RepositoryItem("Dashboard/WelcomeMessage")]
    public WebElement WelcomeMessage { get; set; }
    
    // Test parameter - can be set from test suite
    [TestVariable("0")]
    public string Username { get; set; }
    
    [TestVariable("1")]
    public string Password { get; set; }

    void ITestModule.Run()
    {
        Mouse.Click(UsernameField);
        UsernameField.TextValue = Username;
        
        Mouse.Click(PasswordField);
        PasswordField.TextValue = Password;
        
        Mouse.Click(LoginButton);
        
        // Wait for navigation
        Delay.Milliseconds(2000);
        
        // Assert welcome message is visible
        Validate.Exists(WelcomeMessage, 
            "Dashboard welcome message not found after login");
    }
}

Parameterizing Tests

In Ranorex Studio, bind test variables to data sources:

1. Right-click your test module in the test suite
2. Select Data Binding
3. Choose CSV file or Excel as the source
4. Map columns to TestVariable properties

Example data file (login_data.csv):

Username,Password,ExpectedResult
admin,admin123,success
user,wrong_pass,failure
locked_user,pass,locked

Validation API

// Element exists
Validate.Exists(element);

// Attribute value
Validate.AttributeValue(element, "innertext", "Expected Text");

// Element is enabled/disabled
Validate.EnabledState(button, true);

// Image comparison (pixel-level)
Validate.Image(element, "expected_screenshot.png");

// Custom assertion
if (!element.Visible) {
    Report.Error("Element not visible: " + element.RxPath);
    Keyboard.Press("{ESCAPE}");
}

Building Test Suites

Test suites organize modules into a runnable sequence with conditions and data binding.

TestSuite.rxtst
├── Setup/
│   └── LaunchApplication
├── TestCases/
│   ├── LoginTests/
│   │   ├── ValidLogin (data: login_data.csv)
│   │   └── InvalidLogin
│   └── CheckoutTests/
│       ├── AddToCart
│       └── CompletePurchase
└── Teardown/
    └── CloseApplication

Each test case can have:

• Setup/Teardown — run before/after each test case
• Iteration — run multiple times with different data rows
• Continue on failure — don't stop the entire suite when one test fails

CI/CD Integration

Ranorex Runtime enables headless execution without Ranorex Studio installed.

Command-Line Execution

# Run entire test suite
"C:\Program Files\Ranorex\Ranorex Runner.exe" \
  MySolution.exe \
  /testcasename "LoginTests" \
  /reportlevel:Debug \
  /report:TestReport.rxzlog

# Run with data override
"C:\Program Files\Ranorex\Ranorex Runner.exe" \
  MySolution.exe \
  /testcasename "ValidLogin" \
  /pa:Username=testuser \
  /pa:Password=pass123

Jenkins Pipeline

pipeline {
    agent { label 'windows' }  // Ranorex requires Windows
    
    stages {
        stage('Run Ranorex Tests') {
            steps {
                bat '''
                    "C:\\Program Files\\Ranorex\\Ranorex Runner.exe" ^
                    MySolution.exe ^
                    /testcasename "RegressionSuite" ^
                    /reportlevel:Info ^
                    /report:results\\TestReport.rxzlog
                '''
            }
        }
    }
    
    post {
        always {
            // Archive reports
            archiveArtifacts artifacts: 'results/**/*.rxzlog'
            
            // Parse JUnit XML output
            junit 'results/**/*.xml'
        }
    }
}

GitHub Actions (Windows Runner)

jobs:
  ranorex-tests:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Ranorex Runtime
        run: |
          # Install via Chocolatey or download installer
          choco install ranorex-runtime
          
      - name: Run tests
        run: |
          & "C:\Program Files\Ranorex\Ranorex Runner.exe" `
            .\MySolution.exe `
            /testcasename "SmokeTests" `
            /report:results\report.rxzlog
      
      - name: Upload report
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: ranorex-report
          path: results/*.rxzlog

Ranorex vs Selenium for Web Testing

Selenium is the right choice for web-only testing. Ranorex is the right choice when you need to test native Windows desktop applications, or when a team without coding expertise needs a no-code entry point.

Common Issues and Fixes

Element not found: The RanoreXPath is too specific. Open the object repository, click the element, and use "Find in Application" to verify it still matches. Simplify the path by removing unstable attributes.

Test is slow: Default delays between actions are conservative. Reduce Delay.Milliseconds() values in code modules. For recording playback speed, adjust in the test module settings.

Flaky on CI: CI machines are often slower. Increase element timeouts in repository settings. Add explicit waits for async operations.

Screenshot mismatch: Image-based validations fail when display resolution or DPI differs. Set CI agent resolution to match development machines, or switch to attribute-based validation instead of image comparison.

Summary

Ranorex covers a testing niche that Selenium and Playwright don't: native Windows desktop application automation. Its recorder makes initial test creation accessible, and the C# scripting layer provides the flexibility needed for complex scenarios.

For pure web testing, Selenium or Playwright are better choices. For mixed environments — Windows desktop apps plus web interfaces — or for teams that need codeless test creation, Ranorex is worth evaluating. The free trial is a practical way to test it against your specific application before committing.