1 package com.atlassian.selenium;
2
3 import com.atlassian.webtest.ui.keys.KeyEventType;
4 import com.thoughtworks.selenium.Selenium;
5 import com.atlassian.selenium.visualcomparison.VisualComparableClient;
6
7 import java.util.Collection;
8
9
10 /**
11 * Extends the {@link Selenium} client to provide a more sensible implementation
12 * as well some extra utility methods such as keypress.
13 */
14 public interface SeleniumClient extends Selenium, VisualComparableClient
15 {
16
17 /**
18 * Unlike {@link DefaultSelenium#open}, this opens the provided URL relative to the application context path.
19 * It also waits for the page to load -- a maximum of PAGE_LOAD_WAIT before returning.
20 */
21 public void open(String url);
22
23 /**
24 * Wait for page to load doesn't work the case of non-HTML based resources (like images).
25 * So sometimes you really do want to open a url without waiting.
26 * @param url
27 */
28 public void openNoWait(String url);
29
30 /**
31 * Opens the given URL and waits a maximum of timeoutMillis for the page to load completely.
32 */
33 public void open(String url, long timeoutMillis);
34
35 /**
36 * Overloads {@link #waitForPageToLoad(String)} to take in a long.
37 */
38 public void waitForPageToLoad(long timeoutMillis);
39
40 /**
41 * Waits for the page to load with the default timeout configured in {@link SeleniumConfiguration}.
42 */
43 public void waitForPageToLoad();
44
45 /**
46 * Executes the given Javascript in the context of the text page and waits for it to evaluate to true
47 * for a maximum of {@link SeleniumConfiguration.getActionWait} milliseconds.
48 * @see #waitForCondition(String, long) if you would like to specify your own timeout.
49 */
50 public void waitForCondition(String javascript);
51
52 /**
53 * Executes the given Javascript in the context of the text page and waits for it to evaluate to true
54 * for a maximum of timeoutMillis.
55 */
56 public void waitForCondition(String javascript, long timeoutMillis);
57
58 /**
59 * Waits for the page to finish loading ajax calls, and returns if there are no more ajax calls currently running.
60 * The method will check for a maximum of {@link #ACTION_WAIT} milliseconds
61 * @see #waitForAjaxWithJquery(long) if you would like to specify your own timeout.
62 */
63 public void waitForAjaxWithJquery();
64
65 /**
66 * Waits for the page to finish loading ajax calls, and returns if there are no more ajax calls currently running.
67 * The method will check for a maximum of timeoutMillis
68 */
69 public void waitForAjaxWithJquery(long timeoutMillis);
70
71 /**
72 * Click the element with the given locator and optionally wait for the page to load, using {@link #PAGE_LOAD_WAIT}.
73 *
74 * @param locator the element to click, specified using Selenium selector syntax
75 * @param waitForPageToLoad whether to wait for the page to reload. Don't use this unless the page is completely
76 * reloaded.
77 * @see #click(String, long) if you would like to specify your own timeout.
78 */
79 public void click(String locator, boolean waitForPageToLoad);
80
81 /**
82 * Submit the named form locator and optionally wait for the page to load, using {@link #PAGE_LOAD_WAIT}.
83 *
84 * @param form to click, specified using Selenium selector syntax
85 * @param waitForPageToLoad whether to wait for the page to reload. Don't use this unless the page is completely
86 * reloaded.
87 * @see #submit(String, long) if you would like to specify your own timeout.
88 */
89 public void submit(String form, boolean waitForPageToLoad);
90
91 /**
92 * Click the element with the given locator and wait for the page to load, for a maximum of timeoutMillis.
93 * <p/>
94 * Do not use this method if the page does not reload.
95 *
96 * @param locator the element to click, specified using Selenium selector syntax
97 * @param timeoutMillis the maximum number of milliseconds to wait for the page to load. Polling takes place
98 * more frequently.
99 * @see #click(String, boolean) if you would like to use the default timeout
100 */
101 public void click(String locator, long timeoutMillis);
102
103 /**
104 * Click the element with the given locator and wait for the ajax call to finish.
105 *
106 * @param locator the element to click, specified using Selenium selector syntax
107 */
108 public void clickAndWaitForAjaxWithJquery(String locator);
109
110 /**
111 * Click the element with the given locator and wait for the ajax call to finish.
112 *
113 * @param locator the element to click, specified using Selenium selector syntax
114 * @param timeoutMillis the maximum number of milliseconds to wait for the ajax calls to finish.
115 * @see #clickAndWaitForAjaxWithJquery(String) if you would like to use the default timeout
116 */
117 public void clickAndWaitForAjaxWithJquery(String locator, long timeoutMillis);
118
119 /**
120 * Submit the given form and wait for the page to load, for a maximum of timeoutMillis.
121 * <p/>
122 * Do not use this method if the page does not reload.
123 *
124 * @param form the form to submit
125 * @param timeoutMillis the maximum number of milliseconds to wait for the page to load. Polling takes place
126 * more frequently.
127 * @see #click(String, boolean) if you would like to use the default timeout
128 */
129 public void submit(String form, long timeoutMillis);
130
131 /**
132 * This will type into a field by sending key down / key press / key up events.
133 * @param locator Uses the Selenium locator syntax
134 * @param key The key to be pressed
135 */
136 public void keyPress(String locator, String key);
137
138 /**
139 * This will type into a field by first blanking it out and then sending key down / key press / key up
140 * events.
141 *
142 * @param locator the Selenium locator
143 * @param string the string to type
144 * @param reset Should the field be reset first?
145 */
146 public void typeWithFullKeyEvents(String locator, String string, boolean reset);
147
148 /**
149 * This will type into a field by first blanking it out and then sending key down / key press / key up
150 * events. This really only calls {@link #typeWithFullKeyEvents(String,String,boolean)})}
151 *
152 * @param locator - the usual Selenium locator
153 * @param string the string to type into a field
154 */
155 public void typeWithFullKeyEvents(String locator, String string);
156
157 /**
158 * This will send all the events for a particular character
159 * NOTE: This function will only handle vanilla ascii characters
160 * more exotic characters will be ignored (ie. NO events will be fired).
161 * *
162 * @param locator - the usual Selenium locator
163 * @param character - the character to send
164 * @param eventsToFire - a collection of the types of events to Fire
165 */
166 public void simulateKeyPressForCharacter(final String locator, final Character character, Collection<KeyEventType> eventsToFire);
167
168 /**
169 * This will send all the events for a particular character
170 * NOTE: This function will only handle vanilla ascii characters
171 * more exotic characters will be ignored (ie. NO events will be fired).
172 * This will fire ALL events for the Character
173 * *
174 * @param locator - the usual Selenium locator
175 * @param character - the character to send
176 */
177 public void simulateKeyPressForCharacter(String locator, Character character);
178
179 /**
180 * This will send all the events for a particular special key (for example F1 or the down arrow key)
181 * The keyCode matches the codes in java.awt.event.KeyEvent
182 * NOTE: the return key actually fires events with a keyCode of 13 NOT VK_ENTER
183 * *
184 * @param locator - the usual Selenium locator
185 * @param keyCode - the code for the special Key can use java.awt.event.KeyEvent.XXX to find these
186 * @param eventsToFire - a collection of the types of events to Fire
187 */
188 public void simulateKeyPressForSpecialKey(final String locator, final int keyCode, Collection<KeyEventType> eventsToFire);
189
190 /**
191 * This is a low level function to generate one keyboard event. It would be preferable to use the simulatKeyPress... functions
192 * above.
193 * @param locator - the locator of the element to send the keyevent to
194 * @param eventType - The type of key event
195 * @param keyCode - the keyCode for the keyEvent
196 * @param characterCode - the character code for the key event
197 * @param shiftKey - Is the shift key down?
198 * @param altKey - Is the alt/option key down?
199 * @param controlKey - Is the control key down?
200 * @param metaKey - Is the meta (aka the apple or windows) key down?
201 */
202 public void generateKeyEvent(final String locator, final KeyEventType eventType, final int keyCode, final int characterCode,
203 final boolean shiftKey, final boolean altKey, final boolean controlKey, final boolean metaKey);
204
205 /**
206 * This will send all the events for a particular special key (for example F1 or the down arrow key)
207 * The keyCode matches the codes in java.awt.event.KeyEvent
208 * NOTE: the return key actually fires events with a keyCode of 13 NOT VK_ENTER
209 * This will fire ALL events for the special key.
210 * *
211 * @param locator - the usual Selenium locator
212 * @param keyCode - the code for the special Key can use java.awt.event.KeyEvent.XXX to find these
213 */
214 public void simulateKeyPressForSpecialKey(String locator, int keyCode);
215
216 /**
217 * This sets if subsiquent calls to the keyEvent (@keyDown, @keyPress, @keyUp) fuctions
218 * will set the code in the keyCode or not.
219 * This is applicable to Firefox and webkit.
220 * @param toKeyCode - to set or not to set the keyCode in the event
221 */
222 public void toggleToKeyCode(boolean toKeyCode);
223
224 /**
225 * This sets if subsiquent calls to the keyEvent (@keyDown, @keyPress, @keyUp) fuctions
226 * will set the code in the characterCode or not.
227 * This is applicable to Firefox and webkit.
228 * @param toCharacterCode - to set or not to set the characterCode in the event
229 */
230 public void toggleToCharacterCode(boolean toCharacterCode);
231
232 /**
233 * This will select an option from a {@code select} field.
234 *
235 * @param selectName the select field name
236 * @param label the label to select
237 */
238 public void selectOption(String selectName, String label);
239
240 /**
241 * This will select an option from a {@code select} field. If the field calls executes an ajax call onchange of
242 * the value, this method will wait for that ajax method to finish.
243 *
244 * @param selectName the select field name
245 * @param label the label to select
246 */
247 public void selectOptionAndWaitForAjaxWithJquery(String selectName, String label);
248
249 /**
250 * Checks a checkbox given a name and value.
251 */
252 public void check(String name, String value);
253
254 public void clickLinkWithText(String text, boolean waitForPageToLoad);
255
256 public void clickButton(String buttonText, boolean waitForPageToLoad);
257
258 public void clickButtonAndWaitForAjaxWithJquery(String buttonText);
259
260 public void clickButtonWithName(String buttonName, boolean waitForPageToLoad);
261
262 public void clickButtonWithNameAndWaitForAjaxWithJquery(String buttonName);
263
264 public void clickElementWithTitle(String title);
265
266 public void clickElementWithTitleAndWaitForAjaxWithJquery(String title);
267
268 public void clickElementWithClass(String className);
269
270 public void clickElementWithClassAndWaitForAjaxWithJquery(String className);
271
272 public void clickElementWithCss(String cssSelector);
273
274 public void clickElementWithCssAndWaitForAjaxWithJquery(String cssSelector);
275
276 public void clickElementWithXpath(String xpath);
277
278 public void clickElementWithXpathAndWaitForAjaxWithJquery(String xpath);
279
280 public void typeInElementWithName(String elementName, String text);
281
282 public void typeInElementWithCss(String cssSelector, String text);
283
284 public boolean hasJquery();
285
286 public void start();
287
288 public Browser getBrowser();
289
290 public void seleniumKeyPress(String locator, String key);
291
292 }