fork the sample project from github.
Structure of this chapter
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 structureIf 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.
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:
||Contains code-style settings for the Ranorex Webtestit code editor. Learn more about the editorconfig settings here|
||Stores information about the endpoints that will execute your test. ⇢ Click here to read more about endpoints|
||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|
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:
|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|
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
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 objectsTo 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.
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
pageobjectsfolder of your project and prompt you to name it. Alternatively, you can right-click the
pageobjectsfolder and create the file via the context-menu. Name the file
HeaderPo.tsif you’re using TypeScript, or
HeaderPo.javaif you’re using Java.
The newly created file comes with two default functions
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
pageobjectsfolder in the Project tab and select New > Page Object File from the context menu. Name the new Page Object
DetailPagePo.tsif you’re using TypeScript or
DetailPagePo.javaif you’re using Java.
Add elements to your page objects using Ranorex SelocityNow 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
HeaderPofile. 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
HeaderPohas 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
Repeat above steps for the item count next to the subtotal. Name the new element
cartCount. When you’re finished your
HeaderPoPage Object should look like this:
That’s it for the
HeaderPofor now. Go on and select the
DetailPagePofrom 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|
Add an element manuallyInstead 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
cartConfirmationMessageas a name In the Selector field, add the following:
[role='alert']From the Strategy dropdown, select css Click the Close button
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 actionsWith 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
HeaderPofile from your project’s
searchInputinto the Code tab
- Click the Type into element option in the popup menu
- Name the function
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
HeaderPoPage 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
DetailPagePofrom your project’s
pageobjectsfolder. Implement the following functions:
||Returns the text of the
||Returns the text of the
||Returns the text of the
Eventually, the methods in your
DetailPagePoshould look like this:
With this, we’re ready to automate our test cases.
Write the testTo create a new test file, right-click the
testsfolder 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.tswhen using TypeScript, or
Test1.javawhen using Java.
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 testFinally, 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.
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
reportsin 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
Where to continue from hereWe have created some suggestions for you to read on:
- Learn about selectors and the Elements tab in Ranorex Webtestit
- How to manage Page Objects and effortlessly create Page Object actions with Drag&Drop
- Executing Tests in Ranorex Webtestit and in the CLI to get results quickly
- Configuring Endpoints and connecting to Selenium Grids in the Execution tab
- Working with Reports
- Discovering errors and maintaining your tests using diagnostic mode