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