Getting started

You can use the API in two different ways:

1. In Ranorex Studio through code modules and user code methods

   • This requires no setup other than adding a code module or user code method in Ranorex Studio.

   • Supports C# and VB.NET only.

2. In an external IDE like Visual Studio

   • This requires some setup and is what we focus on in this introduction.

   • Supports any .NET language.

Let’s first go over the key concepts you need to know for using the API.

• Ranorex tests perform actions on UI elements.

• Actions are represented in the API through classes and methods.

• UI elements are addressed in the API either directly as adapters via their RanoreXPath, or as repository items. In both cases, you need Ranorex Spy to identify UI elements.

This example uses Visual Studio for our explanation. The basic principle is always the same and works for other IDEs.

To use the API, you first need to:

• add the Ranorex Studio assemblies as references to a project in your IDE.

• add the main function that will contain your code.

Now you’re ready to write test automation code. At its simplest, this means:

• Use Ranorex Spy to find out what type a UI element is and what its RanoreXPath is

• Write code that instantiates the UI element as an adapter and performs an action on it

Add Ranorex assemblies to your Visual Studio project

Add the main function that will contain your code

 1[STAThread]
 2static void Main(string[] args)
 3{
 4    InitResolver();
 5    RanorexInit();
 6    run();
 7}
 8
 9[MethodImpl(MethodImplOptions.NoInlining)]
10private static void InitResolver()
11{
12    Ranorex.Core.Resolver.AssemblyLoader.Initialize();
13}
14
15[MethodImpl(MethodImplOptions.NoInlining)]
16private static void RanorexInit()
17{
18    TestingBootstrapper.SetupCore();
19}
20
21[MethodImpl(MethodImplOptions.NoInlining)]
22private static int run()
23{
24    //your automation code goes here
25}

As mentioned above, writing automation code means writing code that performs actions on UI elements. To do so, you need to address UI elements in code via instantiating them as adapters

Let’s first look at an isolated code snippet that performs an action on a directly addressed UI element:

1var submitBtn = demoApp.FindSingle<Button>("./?/?/tabpage[@controlname='RxTabIntroduction']/button[@controlname='btnSubmitUserName']");//FindSingle searches a button in the Ranorex Demo App and stores the found element as a variable of type Ranorex.Button
2var text = submitBtn.Text; //gets the text of the above button and stores it as a variable called “text”
3submitBtn.Click(); //clicks this button

To instantiate a UI element as an adapter, you need to know the role or capability of the UI element, its RanorexPath, and to which class the role/capability corresponds to in the Ranorex Studio API. For the first two, you need to use Ranorex Spy:

1. Open your AUT and the standalone version of Ranorex Spy.

2. In Spy, click ELEMENT BROWSER to display the element tree.

3. Find the desired UI element.

   Note
   You can also click the Track button to track the UI element in Windows. It will then be automatically selected in the tree view.

4. With the UI element selected in the tree, you can see its RanoreXPath next to the Track button.

5. For the role/capability, keep the UI element selected and click Overview to the right of the element tree. The headers there are the available roles/capabilities, e.g. Button and UIAutomation.

   Note
   The General and Dynamic capabilities do not work for addressing UI elements, as no corresponding adapter class is available.

Now let’s get the class. For every role or capability a UI element can have (except General and Dynamic), there is at least one corresponding class in the Ranorex namespace. In this example, the corresponding classes for this button are Ranorex.Button and Ranorex.UIAutomation.

You can address the UI element through either, but of course different classes offer different properties and methods, so you need to choose the one that fits your automation task. In the example above, you need the Click() method and the Text attribute. Both are available in the Button class, so this is the one to choose.

With the information from the above steps, you can address the UI element through its adapter class and RanoreXPath. You now know the basics of using the API to write automation code in an external IDE.

Finally, here’s a full example of a short test written using the API. It's a replication of the test from this chapter. There, we created it using the Ranorex Studio UI.

1. Open the Ranorex Studio Demo Application.

2. Enter Harry in the Enter your name field and click Submit.

3. Verify that the welcome message changes accordingly.

4. Reset the welcome message.

5. Close the demo application.

 1using System;
 2using System.Collections.Generic;
 3using System.Linq;
 4using System.Text;
 5using System.Threading.Tasks;
 6using System.Runtime.CompilerServices;
 7using Ranorex;
 8using Ranorex.Core.Repository;
 9using Ranorex.Core;
10using Ranorex.Core.Testing;
11
12
13
14namespace API_RxDemo
15{
16    internal class Program
17    {
18        private const string RxDemoAppFilePath = "RxDemoApp.exe";
19        private const string RelativePathToWelcomeMessage = "./?/?/tabpage[@controlname='RxTabIntroduction']/text[@controlname='lblWelcomeMessage']";
20
21        [STAThread]
22        static void Main(string[] args)
23        {
24            InitResolver();
25            RanorexInit();
26            Run();
27        }
28
29        [MethodImpl(MethodImplOptions.NoInlining)]
30        private static void InitResolver()
31        {
32            Ranorex.Core.Resolver.AssemblyLoader.Initialize();
33        }
34
35        [MethodImpl(MethodImplOptions.NoInlining)]
36        private static void RanorexInit()
37        {
38            TestingBootstrapper.SetupCore();
39        }
40
41        [MethodImpl(MethodImplOptions.NoInlining)]
42        private static void Run()
43        {
44            Host.Local.RunApplication(RxDemoAppFilePath); // Runs the Ranorex Demo Application
45            var timeoutToWaitForAppToBeStarted = Duration.FromMilliseconds(10000);
46            var demoApp = Host.Local.FindSingle<Form>("/form[@controlname='RxMainFrame']", timeoutToWaitForAppToBeStarted);
47
48            var userName = demoApp.FindSingle<Text>("./?/?/tabpage[@controlname='RxTabIntroduction']/text[@controlname='txtUserName']");
49            userName.Click(); // Clicks the name input field
50            userName.PressKeys("Harry"); // type Harry into the input field
51
52            var submitBtn = demoApp.FindSingle<Button>("./?/?/tabpage[@controlname='RxTabIntroduction']/button[@controlname='btnSubmitUserName']");
53            submitBtn.Click(); // Clicks the submit button
54
55            var welcomeMsg = demoApp.FindSingle(RelativePathToWelcomeMessage); // you can also put RanoreXPaths into constants or resources
56            Validate.AttributeEqual(welcomeMsg, "Text", "Welcome, Harry!"); // Verify that the welcome message changes accordingly
57
58            var resetMsg = demoApp.FindSingle<Link>("./?/?/tabpage[@controlname='RxTabIntroduction']/link[@controlname='RxLinkBtnReset']/?/?/link[@accessiblename='Reset']");
59            resetMsg.Click(); // Reset the welcome message
60
61            demoApp.Close(); //Close the application
62        }
63    }
64}

Other Resources