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

    Note

    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 both TypeScript and Java.

    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

    Note

    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.

    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

    Hint

    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

    Note

    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.
    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.

    Reference

    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.

    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. 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
    Repeat above steps for the item count next to the subtotal. Name the new element cartCount. 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 productName 
    The product’s unit price productPrice Use the value below the product name, not from the header
    The “Add to cart” button addToCartButton Right below the unit price

    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 In the Selector field, add the following: [role='alert'] From the Strategy dropdown, select css Click the Close button
    tipp icon

    Hint

    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 file from your project’s pageobjects folder
    • Drag searchInput into the Code tab
    • Click the Type into element option in the popup menu
    • Name the function insertSearchText
    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, just add another parameter to the method sendKeys like this:
    tipp icon

    Hint

    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.
    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.
    Eventually, the methods in your DetailPagePo should look like this:
    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.
    Note icon

    Note

    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. You can, however, switch the individual components.
    Depending on the automation framework and language in use, you will create the two test cases as described in the table above.
    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

    Note

    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.

    Congratulations!

    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