Running a Solution with GitHub Actions

GitHub Actions lets you automate the build and execution of a Ranorex Studio solution in a GitHub repository.

This article explains how to prepare the test machine, create a workflow, configure a self-hosted runner, and run the workflow.

Before you begin

Before setting up GitHub Actions, make sure the following requirements are met:

• Your Ranorex Studio solution already exists.
• TortoiseGit is installed and configured.
• Your solution is stored in a GitHub repository.
• The machine that will run the tests meets the Ranorex Studio prerequisites.
• The machine is prepared to run UI tests.

For Ranorex Studio solutions, a self-hosted Windows runner is required. GitHub Actions routes jobs to self-hosted runners by using labels such as self-hosted, windows, and x64.

How GitHub Actions works with Ranorex Studio

A GitHub Actions workflow defines the steps required to build and run the solution.

After the workflow is created, a self-hosted runner receives the job, checks out the repository, builds the solution, and runs the test.

Step 1: Prepare the test machine

The machine that clones the repository, builds the solution, and runs the test must have the required Ranorex Studio prerequisites installed.

At a minimum, install the components required to build and run the Ranorex Studio solution. The easiest way to ensure this is to install Ranorex Studio on the machine.

After installation:

1. Make sure the machine can access the required repositories and GitHub endpoints.
2. Configure Ranorex licensing so the test machine can obtain a valid license.
3. Verify that the machine is suitable for UI test execution.

Important: For UI tests, do not use a headless environment. The runner machine must have an active user session so the UI can be displayed and automated.

Step 2: Create the workflow

To create a workflow in GitHub:

1. Open your repository in GitHub.
2. Click Actions.
   

GitHub can suggest starter workflows, but the workflow file must be adjusted for your Ranorex Studio solution.

When you create a workflow, GitHub stores the YAML file in the .github/workflows directory in your repository. GitHub Actions workflows define when jobs run, which runner they use, and which steps are executed.

The placeholder file contains examples for common actions in a workflow and can be modified to meet the project’s needs. 

Example 

Workflow on push and pull requests to the main branch is below: 

name: RxDemoAppRegression # Choose a name that makes the most sense to you 
 
on: # This setup will run the workflow on Push and Pull requests to the main code branch 
  push: 
    branches: [ "main" ] 
  pull_request: 
    branches: [ "main" ] 
 
jobs: 
 
  build: 
 
    strategy: 
      matrix: 
        configuration: [Debug] 
 
    runs-on: self-hosted # The Runner must be self-hosted 
     
    # Configure environment variables 
    env: 
      Solution_Name: RxDemoApp.sln # Replace with your solution name 
      Test_Project_Path: RxDemoApp\RxDemoApp.csproj # Replace with the path to your test project 
       
    # Check out code from the repository 
    steps: 
    - name: Checkout 
      uses: actions/checkout@v4 # At the time of writing, v4 is the latest 
      with: 
        fetch-depth: 0 
 
    # Add MSBuild to the PATH: https://github.com/microsoft/setup-msbuild 
    - name: Setup MSBuild.exe 
      uses: microsoft/setup-msbuild@v2 # At the time of writing, v2 is the latest 
 
    # This step is not required for all solutions 
    # Restore the application to populate the obj folder with RuntimeIdentifiers 
    - name: Restore the application 
      run: msbuild $env:Solution_Name /t:Restore /p:Configuration=$env:Configuration 
      env: 
        Configuration: ${{ matrix.configuration }} 
 
    # Build the solution 
    - name: Build solution 
      run: msbuild $env:Solution_Name 
 
    # Run the solution, replacing RxDemoApp with the name of your solution 
    - name: Run the Test Suite 
      run: RxDemoApp/bin/Debug/RxDemoApp.exe 

Workflow notes

• runs-on should target your self-hosted Windows runner.
• actions/checkout@v4 checks out the repository for the workflow. By default, it fetches only a single commit. Setting fetch-depth: 0 fetches the full history.
• microsoft/setup-msbuild@v2 adds msbuild.exe to PATH so it can be used in later steps.
• Adjust the solution name, project path, and executable path to match your own solution structure.

When the content of the Workflow file is correct, the changes can be committed.  If there is already a Runner that is on and listening, it will automatically run the workflow above.  Otherwise, continue to step 3 to configure the Runner and step 4 to manually trigger the Workflow. 

Step 3: Configure the self-hosted runner

To configure a self-hosted runner:

1. In your GitHub repository, click Actions.
2. In the left navigation, click Runners.
3. Click New runner.
4. Follow the GitHub instructions to install and configure the runner on the machine that will run the tests.

A self-hosted runner must be installed and running on the host machine before it can receive jobs.

From this screen, follow the instructions to install and configure the Runner on the machine that will be running the tests.  Do not install the Runner as a service; it must run as a local account, and the account must have an active window session for UI tests to run successfully.  When the setup is completed, you should see that your Runner is connected to GitHub and listening for a command to start jobs.  If not, navigate to the directory you created for your Runner in a Command Prompt window, then execute run.cmd. 

Step 4: Running the workflow

You can start the workflow by triggering the configured event, such as a push or pull request.

If your workflow is configured for pushes to the main branch, commit and push your changes to trigger the workflow automatically.

If a compatible self-hosted runner is online, GitHub sends the job to that runner and starts the workflow.

To monitor the run:

1. Open the repository in GitHub.
2. Click Actions.
3. Open the workflow run you want to inspect.

You can also monitor the runner directly on the test machine.

Conclusion

Now that the basics of the Workflow are complete, it is possible to incorporate other actions and apps into the Workflow to further enhance the Ranorex workflow.