Running a solution with GitHub actions

This guide will walk through the process of setting up your Ranorex Studio solution to run with GitHub Actions.  It is required that your Ranorex Studio solution exists, TortoiseGit is installed and configured, your solution already exists in GitHub, and the machine that will ultimately run the tests the Ranorex Studio pre-requisites have been met. 

Setting up workflows in GitHub

To begin using GitHub Actions, you must first create and configure a Workflow.  Once the Workflow is configured, then a self-hosted Runner can be created to send the solution to the Runner, which will then clone the repository, build the solution, and then run the test.

Step 1: Configuring the environment

The machine that will be responsible for cloning the repository, building the solution, and running the test must first have all Ranorex Studio pre-requisites installed.  This includes the following:

• Microsoft Windows Installer 3.1 or higher
• Microsoft Visual C++ 2017 x86
• Microsoft Visual C++ 2017 x64 (required for 64-bit Windows versions only) 
• Microsoft .NET Framework 4.8
• Visual Studio Build Tools 2019

With these pre-requisites installed, at a minimum the Ranorex Studio Core Libraries must be installed from the Ranorex Studio Installer.  The easiest way to ensure that all pre-requisites are installed is to install Ranorex Studio.  Once installed, configure the Ranorex Studio Licensing application to point to your License Manager so that tests can connect to the License Manager and lease a license to run the test. 

Step 2: Configuring the workflow

Now that the environment is configured, the Workflow can be set up.  The Workflow is what will ultimately be responsible for sending tests to the machine that will run the test automation.  From your Repository in GitHub, click the Actions tab and then click the New Workflow button.  If this is your first Workflow, you will be taken directly to the Choose a Workflow screen: 

On the Choose a Workflow screen, GitHub will suggest the .NET Desktop workflow since your Ranorex Solution is built on the .NET Framework.  Click the Configure button to select this Workflow.  This will create a Workflow YAML file that can now be customized. 

A default .yml file will be created and automatically added to the repository in the .github/workflows directory.  Provide a name for the file in the space provided: 

The placeholder file will contain examples for common actions in a workflow and can be modified to meet the project’s needs.  An example that will trigger the 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 

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: Configuring the Runner

With the pre-requisites now taken care of, it is time to configure the Runner.  From your Repository in GitHub, select the Actions tab, select Runners on the left-hand side, click the New Runner button, and then click the New Self-Hosted Runner button. 

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

The Workflow can be run manually, but to test the YAML configuration, simply Commit and Push from Ranorex Studio (if the above template is used, this will happen automatically) and then keep an eye on your machine with the Runner.  Your test should begin shortly, and you can watch the progress from the screen of the Runner or from the Action tab in your GitHub Repository.  All Ranorex Report data will be logged directly into the result of your test run in GitHub. 

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.