1 package com.atlassian.pageobjects.elements;
2
3 import com.atlassian.annotations.PublicApi;
4 import com.atlassian.pageobjects.elements.timeout.TimeoutType;
5 import org.openqa.selenium.By;
6 import org.openqa.selenium.Dimension;
7 import org.openqa.selenium.Point;
8
9 import java.util.List;
10
11 /**
12 * Represents an HTML element that is expected on a DOM of a page.
13 *
14 * @since 2.0
15 */
16 @PublicApi
17 public interface PageElement extends PageElementFinder
18 {
19 /**
20 * Whether this element is currently on the DOM of the page
21 *
22 * @return True if this element tag exists in the DOM, false otherwise.
23 */
24 boolean isPresent();
25
26 /**
27 * Whether this element is visible on the page
28 *
29 * @return true if this element is visible on the page, false otherwise.
30 */
31 boolean isVisible();
32
33 /**
34 * Whether this element is enabled on the page
35 *
36 * @return True if this element is enabled, false otherwise.
37 */
38 boolean isEnabled();
39
40 /**
41 * Whether this element is selected on the page. Useful on checkboxes and radio buttons.
42 * For checkboxes, returns true if the checkbox is checked.
43 * For radio buttons, returns true if the radio button this class represents is selected.
44 *
45 * @return True if this element is selected, false otheriwse.
46 */
47 boolean isSelected();
48
49 /**
50 * Whether this element has the given class set
51 *
52 * @param className The name of the class to check
53 * @return true if this element's class attribute contains the given classname, false otherwise.
54 */
55 boolean hasClass(String className);
56
57 /**
58 * Get the value of the given attribute of this element.
59 *
60 * @param name The name of the attribute.
61 * @return The attribute's current value, or null if the value is not set
62 */
63 String getAttribute(String name);
64
65 /**
66 * Whether this element has an attribute set to a specific value
67 * @param name The attribute name
68 * @param value The expected value
69 * @return true if attribute is set to the specific value, false otherwise or if attribute is not present
70 */
71 boolean hasAttribute(String name, String value);
72
73 /**
74 * Get the visible innerText of this element, including sub-elements, without any leading or trailing whitespaces.
75 *
76 * @return The innerText of this element.
77 */
78 String getText();
79
80 /**
81 * Get the tag name of this element
82 * @return The tag name
83 */
84 String getTagName();
85
86 /**
87 * Get the value of this element's "value" attribute.
88 *
89 * @return The value of this element's "value" attribute, or null if the value is not set.
90 */
91 String getValue();
92
93 /**
94 * Location of this element on the page (top-left corner)
95 *
96 * @return location of the element on the page
97 */
98 Point getLocation();
99
100 /**
101 * Dimension of this element on the page
102 *
103 * @return
104 */
105 Dimension getSize();
106
107
108 /**
109 * Click this element
110 *
111 * @return The eleemnt that got clicked.
112 */
113 PageElement click();
114
115 /**
116 * Simulate typing into this element. This will append the keystrokes to the end of the text entry element.
117 *
118 * @param keys keys to type
119 * @return The Element that got typed in.
120 */
121 PageElement type(CharSequence... keys);
122
123 /**
124 * Select an element. This method will work against radio buttons, "option" elements within a "select" and checkboxes
125 *
126 * @return The Element that got selected
127 */
128 PageElement select();
129
130 /**
131 * If the element is a checkbox this will toggle the elements state from selected to not selected, or from not selected to selected.
132 *
133 * @return The Element that got toggled
134 */
135 PageElement toggle();
136
137 /**
138 * Clear the value of the text entry element.
139 *
140 * @return The Element that got cleared.
141 */
142 PageElement clear();
143
144 /**
145 * Returns a list of element's that match the given locator within this element
146 * @param locator The locator mecharnism
147 * @return A list of elements that are located within this element.
148 */
149 List<PageElement> findAll(By locator);
150
151 /**
152 * <p/>
153 * Returns an element that will match the given locator within this element.
154 *
155 * <p/>
156 * This method will <i>always</i> return an element instance. Use {@link #isPresent()}
157 * to check whether a corresponding element on the page actually exists.
158 *
159 * @param locator The locator mechanism
160 * @return An element that will be located within this element.
161 */
162 PageElement find(By locator);
163
164 /**
165 * Creates a timed element based on this element's locator.
166 *
167 * @return A TimedElement that is based on this element's locator.
168 */
169 TimedElement timed();
170
171 /**
172 * Gets a <tt>PageElementJavascript</tt> for this element
173 *
174 * @return API to execute javascript on this element.
175 */
176 PageElementJavascript javascript();
177
178 /**
179 * Returns an instance equivalent to this element, with a changed <tt>timeoutType</tt>.
180 *
181 * @param timeoutType new timeout
182 * @return new element with given <tt>timeoutType</tt>
183 */
184 PageElement withTimeout(TimeoutType timeoutType);
185 }