Java Tea User Guide
User Manual:
Open the PDF directly: View PDF .
Page Count: 52
Download | ![]() |
Open PDF In Browser | View PDF |
End-to-end Testing Framework JavaTea User Guide Revision History Version Date 0.0.1 5/1/2019 Author Masayuki Otoshi Description Document Created Table of Contents 1. Introduction ...............................................................................................................................2 2. Installation .................................................................................................................................4 3. Getting Started ...........................................................................................................................5 4. Examples ....................................................................................................................................7 5. Tea Script Language Specifications ...........................................................................................16 6. Preprocessor ............................................................................................................................24 7. TeaBase defined variables and methods ..................................................................................24 8. Custom Shift Methods ..............................................................................................................26 9. Properties File – Multiple Languages .......................................................................................28 10. Template Transformation .....................................................................................................30 11. Debugging Tips .....................................................................................................................40 12. Event Listener .......................................................................................................................43 13. Command Usage ..................................................................................................................45 14. Troubleshooting ...................................................................................................................46 15. Pairwise Testing ....................................................................................................................49 1. Introduction Selenium is a tool widely used to code tests in test automation. It is very efficient to make sure all functions work as we expected. However, in order to make our tests reusable and maintainable, for example, applying Page Object Model (POM), some amount of programming is required. With this approach, you need to create page classes and define properties that represent elements to be displayed on target web page. This concept works fine while your web application works stable. But, in real word, we need to continuously change the code to enhance features and fix issues. The changes break existing tests and you need to spend time to fix. Because of this, developers spends a lot of time to manage tests as well as application code. To reduce the cost of test automation, testing tool must be highly flexible and describable. JavaTea is designed to capture web elements based on text strings shown on the web page to provide an intuitive and easy way to point the target element. 0 First Name John -2 Last Name Smith -1 Email your@email Date of Birth 12 / 2 31 1 / 1911 4 3 Suppose we have the above web page and want to populate values in each input element. Now you can get an element of the 'Email' label with the expression below: 'Email' Tea script finds a text element from the page by using the text 'Email'. Also it allows you to access other input elements around the text element by using the index number from the text. Since we are on the Email label, the index number is now numbered as shown below: John Smith Email -2 -1 0 'Email'<< 'Email'< your@email 1 'Email'> 12 31 1911 2 3 4 'Email'>> 2 To move the index, '>' and '<'operators can be used. The > moves the index to the right and < operator moves to the left. Likewise, '>>' and '<<' operators move by two input elements to the right and left, respectively. If you want to enter an email address in the Email input box, you can describe the script using the > operator: #'Email'> = 'your@email'; If you want to enter your date of birth (for example, December 31st, 1911), describe this: #'Email'>> = 12 31 1911; This expression tries to access the second input element on the right direction from the Email label, which is the input box next to 'Date of Birth' label on the right. After the first value '12' is entered, the index is automatically counted up and the index becomes 3, which is now points to the second input box for the Date of Birth. So, the number '31' is populated into the second input box, and the index is also counted up again. The last number '1911' is populated into the third input box. Next example is using < operator. If you want to enter first and last names (first name: John, last name: Smith), use this expression: #'Email'< = 'Smith' 'John'; The '<' operator sets index to -1 from the current position, thus, the first value 'Smith' is set to Last name input box. This time, the index is decreased and the value becomes '-2', which points to the First name input box. Thus, the next value 'John' is populated into the First name input box. In order to show example to use < operator, I accessed starting from the Email label, however, in real world, we usually gets the first label on the page and simply enter the values from the top to bottom. # 'First name'> = 'John' 'Smith' 'your@email' // Email 12 31 1911 // Date of birth ; Or you can also specify label text for each element in order to make your script robustness for future changes: # 'First name'> = 'John' 'Smith' 'Email'> = 'your@email' 'Date of Birth'> = 12 31 1911 ; 3 The tea script is described in Java code, and it is compiled as a Java class. Thus, you can easily integrate existing other Java libraries. Also you can debug the Java code compiled from Tea script using your favorite IDE. JavaTea also supports pairwise testing with using 2 and 3-wise algorithm to reduce the number of combinations. A test script created for a single test scenario can be easily extended to the script for pairwise testing by adding possible values to each element. For more details, please see chapter Pairwise Testing. 2. Installation Dependencies JavaTea requires the following software: Java SE Version 8 or above https://www.oracle.com/technetwork/java/javase/ Maven Version 3.1.6 or above https://maven.apache.org/ Chrome browser https://www.google.com/chrome/ ChromeDriver (WebDriver for Chrome) http://chromedriver.chromium.org/ In this document, we assume that Maven and ChromeDriver are installed in the following folder structure: / (Root) ├── apache-maven-3.6.1 │ └── ... │ ├── webdrivers │ └── chromedriver.exe └── ... The apache-maven and webdrivers directories should be placed on your system PATH. SET PATH=%PATH%;/apache-maven-3.6.1;/webdrivers 4 3. Getting Started Download, Compile and Run JavaTea samples are available to get from the site: https://github.com/teafarm/javatea/tree/master/examples/ We here show one of easiest samples, how to run GoogleSearch test. Step 1. Download the following files: pom.xml https://github.com/teafarm/javatea/tree/master/examples/GoogleSearch/pom.xml GoogleSearchTest.javat https://github.com/teafarm/javatea/tree/master/examples/GoogleSearch/src/test/G oogleSearchTest.javat Store the files in the following folder structure: . (Current) ├── pom.xml ├── src │ └── test │ └── javat │ └── GoogleSearchTest.javat └── ... Step 2. Compile and Run tests C:> SET PATH=/apache-maven-3.6.1/bin;/webdrivers;C:/Windows/System32 C:> mvn exec:java C:> mvn test A chrome browser will be opened and show a Google site. And a keyword search will be executed automatically. 5 Basic Syntax To understand basic syntax on JavaTea and Tea script, go back to previous chapter and see the sample code. import org.junit.jupiter.api.Test; public class GoogleSearchTest extends tea.TeaBase { @Test public void test() { createDriver('chrome'); driver.get('http://www.google.com'); # 'name:q' = 'Test Tool' true ; } } There are the following JavaTea specific rules: Rule 1: A test class must inherit from tea.TeaBase class: public class GoogleSearchTest extends tea.TeaBase { Rule 2: createDriver() must be called with a browser name before starting to access target web pages. Once you call this, a WebDriver object is created internally and available to use through a property ‘driver’. createDriver('chrome'); Rule 3: driver.get() must be called to display the target web page. driver.get('http://www.google.com'); Rule 4: Tea script must be described between # and ; or # and #. #'name:q' = 'Test Tool'; As for # and # syntax, the second # can be omitted if the script ends with ‘,’ or ‘)’. assertEquals(#'NAME'@>, 'John', 'Name entered'); The above code can be described as show below with the second #: assertEquals(#'NAME'@>#, 'John', 'Name entered'); 6 4. Examples This chapter shows some useful examples to understand how to compile and run JavaTea tests and how to describe Tea scripts in it. Locations Example The first example is Locators. This example accesses the web page shown below and shows various ways to find element objects: Text locator (text:) Text locator is the most-used locator in JavaTea. It finds a web element by a text displayed on the page. The text must exact match with the body text of a tag. For example, if you want to find ‘Name’, it has to be defined as Name. If it may contains extra spaces such as Name , use partial text locator instead. To use a text locator, add ‘text:’ prefix on the target text string. For example, if you want to find a text element of label ‘Name’, describe as shown below: 'text:Name' Or you can also simply specify the label text only (‘text:’ is optional) 'Name' If you access the text element in a function parameter, use # # syntax. assertEquals(#'Name', 'Name', 'text locator'); 7 Partial Text locator (partial:) Partial text locator finds an element by using a part of text string. With specifying the partial: prefix, you can find Name text element by using a partial string, for example, ‘ame’. 'partial:ame' The ‘partial:ame’ matches all displayed text elements which contains a text ‘ame’, e.g. ‘Name’, ‘frame’, ‘america’ XPath locator (xpath:) XPath locator finds an element by using a XPath expression. The expression below returns an input element whose id attribute is ‘name’: 'xpath://input[@id="name"]' ID locator (id:) ID locator finds an element by using an id attribute value. The expression below returns a tag whose id attribute is ‘name’: 'id:name' Name locator (name:) Name locator finds an element by using a name attribute value. The expression below returns a tag whose name attribute is ‘option-value’: 'name:option-value' Link Text locator (linkText:) Link Text locator finds an element by using a text string of a hyper link. The expression below returns an anchor link tag whose body text exacts match with the given text ‘Visit JavaTea site’: 'linkText:Visit JavaTea site' Partial Link Text locator (partialLinkText:) Partial Link Text locator finds an element by using a text string of a hyper link with using partial match condition. The expression below returns an anchor link tag whose body text contains the given text ‘JavaTea site’: 'partialLinkText:JavaTea site' Class Name locator (className:) Class Name locator finds an element by using a class attribute value. The expression below returns a tag whose class is ‘label’, class=”label”: 'className:label' 8 Tag Name locator (tagName:) Tag Name locator finds an element by using a tag name. The expression below returns a tag whose tag name is h2: 'tagName:h2' CSS Selector locator (cssSelector:) CSS Selector locator finds an element by using a CSS Selector expression. The expression below returns a tag whose id attribute is ‘name’: 'cssSelector:#name' This Locators example contains a sample code to obtain a TeaElement object by using # # syntax. TeaElement name = #'id:name'#; The TeaElement implements WebElement interface, so you can get the element information through the APIs. name.getTagName(); name.getAttribute('id'); name.getText(); name.getCssValue('font-family'); name.getLocation(); name.getSize(); 9 ArraySuffix (and Shift) Example Locator returns the first element if it found more than one element with the given condition. If you want to access another element, for example the second element, use array suffix to specify the index. The index number starts with zero. 'Name'[0] 'Name'[1] 'Name'[2] // returns the first Name text element // returns the second Name text element // returns the third Name text element Once you obtained an element object, you can move to another form element (input, button, select, etc) by using shift operator ‘>’. 'Name'> // returns the first input element displayed right next to the Name element 'Name'>> // returns the second input element 'Name'2> // returns the second input element 'Name'>>> // returns the third input element 'Name'3> // returns the third input element 10 Elements Example This sample shows ways to set a value into various type of elements. Input element Enter a value ‘John Smith’ into an input element displayed right next to ‘Name’ text element. Name 1) Clear and enter the given value. 'Name'> = 'John Smith' 2) Enter the given value Keep the original value and append the given value (Use += assignment) 'Name'> += ' suffix' Select element - single selection There are some ways to select an option. Place New York 1) Select an option by the displayed text ‘Tokyo’. (Use an equal assignment) 'Place'> = 'New York' 2) Select an option by the option value ‘ny’. (Use @= assignment) 'Place'> @= 'ny' 3) Select an option by the display text with using a regular expression. (Use /…/ leteral) (Select an option text starting with ‘New’) 'Place'> = /New.*/ Select element - multiple selection Select options by the displayed texts. (Use an array). Color Red Yellow Blue 'Color'> = ['Red', 'Blue'] 11 Radio button Click on a radio button (Use true literal). Type Auto Truck 1) Click on Auto radio button. 'Type'> = true 2) Click on Truck (Skip Auto radio button). 'Type'> = false true or 'Truck'< = true Check box Click on a check box (Use true literal). Agreement 'Agreement'> = true Button element Click on a button (Use true literal). Next 'Next' = true Note that ‘>’ is not needed to specify. In this case, we want to click the ‘Next’ button itself. 12 Wizard Example This is a realistic example compared to previous ones. We here test HTML pages with wizard style. There are two pages titled Page 1 and Page 2. This sample enters a name, an email address and select a place on the first page. Then the second page shows the values entered. Here is the JavaTea file to test the pages above. WizardTest.javat import static tea.TeaAssert.assertEquals; import org.junit.jupiter.api.Test; public class WizardTest extends tea.TeaBase { @Test public void test() { createDriver('chrome'); driver.get(new java.io.File('Page1.html').toURI().toString()); # 'Name'> = 'John' 'john@email' 'Tokyo' true ; assertEquals(#'NAME'@>, 'John', 'Name entered'); assertEquals(#'EMAIL'@>, 'john@email', 'Email entered'); assertEquals(#'PLACE'@>, 'Tokyo', 'Place selected'); 13 driver.quit(); } } The main Tea script code in this sample is this: 'Name'> = 'John' 'john@email' 'Tokyo' true The assignment statement in the first line represents sending a value to Name input field. The ‘Name’ is a text locator which returns a text element object of the Name label. But > operator is attached on the right, so it actually returns a Name input element object displayed right next to the Name label. Thus, the test string ‘John’ is set in the Name field after execution of this line. The assignment statement also counts up element index pointing to current element. Thus current element index is now pointed to Email input field. After the first line, there is a value defined in each line. This is because the first line element index has already set. Since JavaTea moves among elements automatically when a value is set, you don’t have to specify where you set the value. The second text string ‘john@email’ is set into the Email field, and element index is increased and points to the next input element. Likewise, the third line selects ‘Tokyo’ from the selection box. And the fourth line clicks on the Next button. After submitted the form on the Page 1, the sample code validates the values entered with the code below: assertEquals(#'NAME'@>, 'John', 'Name entered'); assertEquals(#'EMAIL'@>, 'john@email', 'Email entered'); assertEquals(#'PLACE'@>, 'Tokyo', 'Place selected'); The assertEquals() takes three parameters: void assertEquals( TesElement actual, String expected, String message ); To set an actual value displayed on the Page 2, we want to use a Tea script. So the first parameter starts with a # sign, and specify the label text of the target value. Next we need to make a shift and get a target text string of Name. Although we used > operator to shift and find an input element, this time we need to use @> operator instead. It is because the target operator is read-only text element, not editable one. ‘Name’@> finds a text string displayed right next to the ‘Name’ label. In this sample, it is expected to be ‘John’. If the application works fine as expected, the first parameter in the assertion returns ‘John’ and it matches with the second parameter which is an expected value. 14 In the sample folder, run the following commands to compile and run the test. C:> SET PATH=/apache-maven-3.6.1/bin;/webdrivers;C:/Windows/System32 C:> mvn exec:java C:> mvn test 15 5. Tea Script Language Specifications This chapter describes language specifications of Tea script. Tea script can be described between # and ; or # and # in Java code. Expression #