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