Quickstart: Create your first test | Ranorex Webtestit User Guide
WebtestitUser GuideQuickstart: Create your first test

Quickstart: Create your first test

In this tutorial, you will create your first UI test with Ranorex Webtestit. You are going to automate parts of our Demoshop example step by step. You can either create all the source files yourself by following this tutorial or fork the sample project from github.

Structure of this chapter

    Note icon


    Do not change the name of the folder or the file. If you remove the settings file (“Ranorex.rxsettings”), the solution settings stored on the local machine are automatically used during test execution. If you open the settings file, it is shown in its raw format. It is not recommended to edit the file in this view.

    The resources for this tutorial are available in TypeScript, Java and Python.

    The project structure

    If you haven’t created a new project yet, click the New Project link on the Welcome tab, or go to File > New Project.

    In the Create new project dialog, specify a name and a location for your project, then select the scripting language you would like to use.

    After clicking on Save Ranorex Webtestit will create your project and set up the required components to run a test.

    Note icon


    Your choice of programming language defines the automation framework being set up for you. If you select TypeScript, Ranorex Webtestit generates a Protractor environment for you. If you select Java instead, a TestNg application is set up. If you choose Python, Ranorex Webtestit will generate unittest environment.

    The project tab

    You can inspect your newly generated project’s structure in the Project tab. Ranorex Webtestit automatically created folders for your test suite and Page Objects. The files you can see in the project’s root directory are used for configuring your test and setting up your environment to run it. Noteworthy config files in the project are:

    Filename Description
    .editorconfig Contains code-style settings for the Ranorex Webtestit code editor. Learn more about the editorconfig settings here
    *.endpoints.json Stores information about the endpoints that will execute your test. ⇢ Click here to read more about endpoints
    webtestit.json Contains project specific options for Ranorex Webtestit test projects. All settings defined here are scoped to a single project as opposed to global settings, which you can access via the main menu File > Preferences > User Settings

    Analyze the site under test (SUT)

    In this tutorial, we’re going to automate the Demoshop. You can find it here. Go right ahead and have a look at it.

    The main page of the Demoshop consists of different parts:

    The header area with the menu and the search field

    The content area with the products listed

    The Demoshop contains various other pages. For this tutorial, we will search for a product and add it to the cart. Let’s create some test cases, which we will then automate:

    # Title Description
    1 Search for an item GIVEN the Demoshop is displayed
    WHEN the user enters “Super” as the search term and hits Enter
    THEN the detail page for “Super Cool Goo” is displayed
    And the product name equals “Super Cool Goo”
    And the price equals €1,500.00
    2 Add an item to the cart GIVEN the detail page for “Super Cool Goo” is displayed
    WHEN the user clicks the “Add to cart” button
    THEN a confirmation message is displayed
    And the item counter displays 1
    And the Subtotal in the cart area equals the product’s price
    tipp icon


    The test case description uses Gherkin syntax. It’s a simple method of defining test cases. Every statement contains three keywords:

    • GIVEN describes the current state, also known as the precondition
    • WHEN describes the user’s actions
    • THEN describes the result of those actions, also known as assertions

    The combination of those keywords is called a scenario. You can use logical operators (and/or) to link multiple statements in any of the blocks to create more complex scenarios.

    When designing the test case, we only describe the expected behavior of the application. Any deviation from this is unexpected and therefore treated as a test failure.

    Now let’s automate these test cases using Ranorex Webtestit!

    Create page objects

    To access all the elements needed for our test cases we need to create selectors for them. Selectors are organized into Page Objects. You can read more about selectors here.

    Since we don’t have any Page Object files yet, we need to create one.

    Note icon


    Page Objects not only contain selectors, but also the simulated user inputs. In fact, it is highly recommended to expose only the Page Object actions to the individual test cases. This is called the Page Object Pattern and described here.

    Click the New Page Object file button inside the project tree toolbar. Ranorex Webtestit will create a new file in the pageobjects folder of your project and prompt you to name it.

    Alternatively, you can right-click the pageobjects folder and create the file via the context-menu. Name the file HeaderPo.ts if you’re using TypeScript or HeaderPo.java if you’re using Java. If you’re using Python, however, you need to use snake case (an underscore character and no spaces between characters), so the Page Object name should be header_po.py.

    The newly created file comes with two default functions open and getTitle. Our Page Object will contain all the selectors and actions we need in the header of the Demoshop.


    For better maintainable tests it’s crucial to analyze your website’s or app’s structure and compartmentalize it into Page Objects. You can read more about Page Objects in  ⇢ chapter 3 of this guide

    Now create another Page Object for the detail page. Right-click the pageobjects folder in the Project tab and select New > Page Object File from the context menu. Name the new Page Object DetailPagePo.ts if you’re using TypeScript or DetailPagePo.java if you’re using Java. Again, since we use snake case in Python, name new Page Object detail_page_po.py.

    Add elements to your page objects using Ranorex Selocity

    Now that we have separated our webshop’s structure into Page Objects, we need to add the elements required to run our test cases. We’re going to use Ranorex Selocity to quickly identify them and add all the selectors needed.

    If you haven’t installed Ranorex Selocity yet, you can refer to the previous section of this Chapter explaining how to install the Ranorex Selocity Extension for Chrome. Refresh the web page if you don’t see the Selocity extension after installation.

    We begin by adding elements to the HeaderPo file. Select it in your Project tab to open it in Ranorex Webtestit (check the Title in the Page Object tab).

    Open Chrome and navigate to https://demoshop.webtestit.com/. Locate the search input in the header area and right-click it. Select Inspect from the context menu.

    Open the Ranorex Selocity tab in the Elements section. If you don’t see it, click the arrow in the Section’s menu or expand the DevTools window. Click the Connect button to connect Ranorex Selocity to Webtestit. Click the Send selector to Ranorex Webtestit button next to the XPath selector.

    Switch back to Ranorex Webtestit. Locate the Elements tab and find the received element there. Click on it to expand it, and you will see that the selector and the selector’s type have been sent successfully, along with an automatically generated name. We would like a more descriptive name than the generated one though, so let’s rename the element to searchInput in Typescript and Java.
    In Python, we will again use snake case. However, when naming variables in Python we need to add a leading underscore as well, so we’ll rename our element _search_input. Click on Close or press ENTER to collapse the element.

    Notice what happened in your project:

    • Ranorex Webtestit created a folder named screenshots which contains an image of your element
    • Your Page Object file HeaderPo has been edited. The element is a member of the class and was added automatically

    Now let’s add the subtotal label. Use a CSS selector this time:

    Locate and right-click the subtotal in the header area

    Select Inspect from the context menu

    In Ranorex Selocity click the Send selector to Ranorex Webtestit button

    Name the new element cartAmount (or _cart_amount in Python).

    Repeat above steps for the item count next to the subtotal. Name the new element cartCount (or _cart_count in Python). When you’re finished your HeaderPo Page Object should look like this:

    That’s it for the HeaderPo for now. Go on and select the DetailPagePo from your Project tab next.

    We’ll need some selectors from the “Super Cool Goo” detail page. Open https://demoshop.webtestit.com/product/super-cool-goo in your browser. Add the following elements with Ranorex Selocity and name them like described in the table below:

    Item & Title Hints Screenshot
    The product name
    The product’s unit price
    Use the value below the product name, not from the header
    The “Add to cart” button
    Right below the unit price

    * In Python, use snake case and leading underscore for elements’ names respectively, e.g. _product_name, etc.

    Add an element manually

    Instead of using Ranorex Selocity, you can also create elements manually. For our final needed selector, we are going to choose this option. It’s the Remove button in the cart overlay.

    Click the + button in the Elements tab to create a new element

    Provide cartConfirmationMessage as a name (_cart_confirmation_message in Python)

    In the Selector field, add the following: [role='alert']

    From the Strategy dropdown, select css

    Click the Close button

    tipp icon


    You can verify if a selector works by sending it back to Ranorex Selocity. To do so, open the element you want to examine and click the Edit with Ranorex Selocity button.

    Ranorex Selocity will only be able to locate the element you just added if you click the “Add to cart” button in the detail page first.

    Notice how this selector gets automatically added as a member to your Page Object file but, in this case, there is no screenshot provided.

    If you want to use the screenshot feature, you would have to make them yourself. Learn more about selectors in ⇢ Chapter 2 of this guide

    Create page object actions

    With all our selectors set up, we can now write some actions that the automation framework is going to execute for us.

    Let’s start by searching for our t-shirt. In the real world, a user would click the search input and enter a search term. Remember that test automation is essentially simulating the user. That’s why we are going to do exactly the same.

    • Select the HeaderPo (header_po) file from your project’s pageobjects folder
    • Drag searchInput (_search_input) into the Code tab
    • Click the Type into element option in the popup menu
    • Name the function insertSearchText (insert_search_text in Python)

    The generated method is a simple construct to quickly get started and save on the amount of code you have to write.

    After sending the text, we want to start the search by pressing the ENTER key. To do so, Ranorex Webtestit adds the sendKeys (send_keys) parameter to the method automatically. Your code should look like this:

    public void insertSearchText(String text) {
      this.wait.until(ExpectedConditions.visibilityOfElementLocated(this.searchInput)).sendKeys(text, Keys.RETURN);
    def insert_search_text(self, text):
        return self
    public async insertSearchText(text: string): Promise {
      await browser.wait(ExpectedConditions.visibilityOf(element(this.searchInput)), browser.allScriptsTimeout, this.searchInput.toString());
      await element(this.searchInput).sendKeys(text, Key.ENTER);
      return this;
    tipp icon


    Generated Page Object actions are created from templates. You can customize the templates according to your website’s or application’s requirements. Read more about
    customizing your templates in Chapter 3 of this guide.

    From the remaining elements within our HeaderPo Page Object we want to get the text. Repeat the above actions, but this time use the option Get element’s text in the popup menu and return the text string, or copy the source code below to do so.

    public String getCartAmount() {
      return this.wait.until(ExpectedConditions.visibilityOfElementLocated(this.cartAmount)).getText();
    public String getCartCount() {
      return this.wait.until(ExpectedConditions.visibilityOfElementLocated(this.cartCount)).getText();
    def get_cart_amount(self):
        cart_count_count = self.wait.until(EC.visibility_of_element_located(self._cart_count)).text
        return cart_count_count
    def get_cart_count(self):
        cart_count_text = self.wait.until(EC.visibility_of_element_located(self._cart_count)).text
        return cart_count_text
    public async getCartAmount(): Promise {
      await browser.wait(ExpectedConditions.visibilityOf(element(this.cartAmount)), browser.allScriptsTimeout, this.cartAmount.toString());
      return await element(this.cartAmount).getText();
    public async getCartCount(): Promise {
      await browser.wait(ExpectedConditions.visibilityOf(element(this.cartCount)), browser.allScriptsTimeout, this.cartCount.toString());
      return await element(this.cartCount).getText();

    Well done! Now select the DetailPagePo from your project’s pageobjects folder.

    Implement the following functions:

    Filename Description
    getProductName* Returns the text of the productName element.
    getProductPrice* Returns the text of the productPrice element.
    addProductToCart* Clicks the addToCartButton
    getConfirmationMessage* Returns the text of the cartConfirmationMessage element.

    *In Python, use snake case for functions’ names respectively

    Eventually, the methods in your DetailPagePo should look like this:

    public String getProductName() {
      return this.wait.until(ExpectedConditions.visibilityOfElementLocated(this.productName)).getText();
    public String getProductPrice() {
      return this.wait.until(ExpectedConditions.visibilityOfElementLocated(this.productPrice)).getText();
    public void addProductToCart() {
    public String getConfirmationMessage() {
      return this.wait.until(ExpectedConditions.visibilityOfElementLocated(this.cartConfirmationMessage)).getText();
    def get_product_name(self):
        product_name_text = self.wait.until(EC.visibility_of_element_located(self._product_name)).text
        return product_name_text
    def get_product_price(self):
        product_price_text = self.wait.until(EC.visibility_of_element_located(self._product_price)).text
        return product_price_text
    def add_product_to_cart(self):
        return self
    def get_confirmation_message(self):
        cart_confirmation_message_text = self.wait.until(EC.visibility_of_element_located(self._cart_confirmation_message)).text
        return cart_confirmation_message_text
    public async getProductName(): Promise {
      await browser.wait(ExpectedConditions.visibilityOf(element(this.productName)), browser.allScriptsTimeout, this.productName.toString());
      return await element(this.productName).getText();
    public async getProductPrice(): Promise {
      await browser.wait(ExpectedConditions.visibilityOf(element(this.productPrice)), browser.allScriptsTimeout, this.productPrice.toString());
      return await element(this.productPrice).getText();
    public async addProductToCart(): Promise {
      await browser.wait(ExpectedConditions.visibilityOf(element(this.addToCartButton)), browser.allScriptsTimeout, this.addToCartButton.toString());
      await element(this.addToCartButton).click();
      return this;
    public async getConfirmationMessage(): Promise {
      await browser.wait(ExpectedConditions.visibilityOf(element(this.cartConfirmationMessage)), browser.allScriptsTimeout, this.cartConfirmationMessage.toString());
      return await element(this.cartConfirmationMessage).getText();

    With this, we’re ready to automate our test cases.

    Write the test

    To create a new test file, right-click the tests folder in your project and select New > Test file from the context menu. Ranorex Webtestit will generate a new class for you and wait for you to name it. Name the file Test1.ts when using TypeScript, or Test1.java when using Java. This time, we won’t use snake case for Python. We’ll use camelCase and name our test file test1.py.

    Note icon


    The actual test file should orchestrate the actions being executed against your website or app. It is good practice to leave the actions themselves in the Page Objects to ensure good maintainability of your test.

    The most important part of each Test Case is the assertion at the end of the block. You use it to verify that the website’s or application’s behavior matches your expected behavior and, therefore, define if the test fails or passes. For the assertion of elements, there are various Assertion Frameworks available.

    Ranorex Webtestit will bundle your project with an Assertion Framework depending on the scripting language you selected. If you choose to write tests in Java the TestNG framework is provided. In case you’re using TypeScript, Protractor together with Jasmine is the default setup. For Python users, unittest environment is provided. You can, however, switch the individual components.

    Depending on the automation framework and language in use, you will create the three test cases as described in the table above.

    public void SearchForItemTestCase() {
      // 1. Arrange
      // Create a new Page Object instance by right-clicking and
      // selecting "Instantiate Page Object" at the bottom
      HeaderPo header = new HeaderPo(driver);
      DetailPagePo detail = new DetailPagePo(driver);
      // 2. Act
      // Call an existing action from your initialized Page Object
      // 3. Assert
      // Use TestNG assertions to verify results.
      // e.g.:
      // Assert.assertEquals(title, "Test Automation for GUI Testing | Ranorex");
      Assert.assertEquals(detail.getProductName(), "Super Cool Goo");
      Assert.assertEquals(detail.getProductPrice(), "€1,500.00");
    public void AddItemToCartTestCase() {
      HeaderPo header = new HeaderPo(driver);
      DetailPagePo detail = new DetailPagePo(driver);
      Assert.assertTrue(detail.getConfirmationMessage().contains("“Super Cool Goo” has been added to your cart"));
      Assert.assertEquals(header.getCartCount(), "1 item");
      Assert.assertEquals(header.getCartAmount(), "€1,500.00");
    def test_search_for_item(self):
        driver = self.get_driver()
        1. Arrange
        Create a new Page Object instance by right-clicking into
        the code editor and selecting "Instantiate Page Object"
        at the bottom of the context menu
        header = header_po(driver)
        detail = detail_page_po(driver)
        2. Act
        Call an existing action from your Page Object instance
        3. Assert
        Use unittest assertions to verify results.
        self.assertEqual(title, "Test Automation for GUI Testing | Ranorex")
        self.assertEqual(detail.get_product_name(), "Super Cool Goo")
        self.assertEqual(detail.get_product_price(), "€1,500.00")
    def test_add_item_to_cart(self):
        driver = self.get_driver()
        header = header_po(driver)
        detail = detail_page_po(driver)
        self.assertTrue(detail.get_confirmation_message in "“Super Cool Goo” has been added to your cart")
        self.assertEqual(header.get_cart_count(), "1 item")
        self.assertEqual(header.get_cart_ammount(), "€1,500.00")
    it('should find a product', async () => { 
      // 1. Arrange
      // Create a new Page Object instance by right-clicking and
      // selecting "Instantiate Page Object" at the bottom
      const header = new HeaderPo();
      const detail = new DetailPagePo();
      await header.open('https://demoshop.webtestit.com');
      // 2. Act
      // Call an existing action from your initialized Page Object
      await header.insertSearchText('Super');
      // 3. Assert
      // Use jasmine to verify results.
      // e.g.:
      // await expect(await title).toEqual('Test Automation for GUI Testing | Ranorex');
      await expect(await detail.getProductName()).toEqual('Super Cool Goo');
      await expect(await detail.getProductPrice()).toEqual('€1,500.00');
    it('should add the product to the cart', async () => {
      const header = new HeaderPo();
      const detail = new DetailPagePo();
      await detail.open('https://demoshop.webtestit.com/product/super-cool-goo/');
      await detail.addProductToCart();
      await expect(await detail.getConfirmationMessage()).toContain('“Super Cool Goo” has been added to your cart');
      await expect(await header.getCartCount()).toEqual('1 item');
      await expect(await header.getCartAmount()).toEqual('€1,500.00');

    With this, we’re ready to automate our test cases.

    Execute your test

    Finally, it’s time to verify that our experiment works. For this to happen we have to create an endpoint first. An endpoint is a set of configurations about the runtime environment of your test. It defines which browser or which operating system to use, and much more.

    Note icon


    Thanks to Selenium WebDriver’s JsonWireProtocol the runtime environment can actually be anywhere in the world, as the commands for automation are being sent over HTTP.

    We are going to create a local Chrome endpoint and execute our test on it.

    Locate the Execution tab

    Click the + button

    In the Endpoint dialog put the following information:

    Note: Your Chrome version may differ from the screenshot

    Click Save endpoint

    You can learn more about Endpoints in ⇢ chapter 4 of this guide.


    If you followed all the steps in this tutorial, your test cases should execute without errors. Ranorex Webtestit will create a new folder reports in your project. Clicking an XML file in there will open the Report tab showing you the results of your run.

    You have also learned:

    • How to create Page Objects in Ranorex Webtestit
    • How to import elements into Page Objects using Ranorex Selocity
    • How to create elements manually
    • How to quickly create Page Object actions using drag&drop
    • How to create an endpoint and execute your test