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