1 | import { ILocation, WebDriver, WebElement } from '../';
|
2 | import { Executor } from './command';
|
3 |
|
4 | /**
|
5 | * Defines the reference point from which to compute offsets for
|
6 | * {@linkplain ./input.Pointer#move pointer move} actions.
|
7 | */
|
8 | export enum Origin {
|
9 | /** Compute offsets relative to the pointer's current position. */
|
10 | POINTER = 'pointer',
|
11 | /** Compute offsets relative to the viewport. */
|
12 | VIEWPORT = 'viewport',
|
13 | }
|
14 |
|
15 | /**
|
16 | * Enumeration of the buttons used in the advanced interactions API.
|
17 | */
|
18 | export enum Button {
|
19 | LEFT = 0,
|
20 | MIDDLE = 1,
|
21 | RIGHT = 2,
|
22 | }
|
23 |
|
24 | export interface IKey {
|
25 | NULL: string;
|
26 | CANCEL: string; // ^break
|
27 | HELP: string;
|
28 | BACK_SPACE: string;
|
29 | TAB: string;
|
30 | CLEAR: string;
|
31 | RETURN: string;
|
32 | ENTER: string;
|
33 | SHIFT: string;
|
34 | CONTROL: string;
|
35 | ALT: string;
|
36 | PAUSE: string;
|
37 | ESCAPE: string;
|
38 | SPACE: string;
|
39 | PAGE_UP: string;
|
40 | PAGE_DOWN: string;
|
41 | END: string;
|
42 | HOME: string;
|
43 | ARROW_LEFT: string;
|
44 | LEFT: string;
|
45 | ARROW_UP: string;
|
46 | UP: string;
|
47 | ARROW_RIGHT: string;
|
48 | RIGHT: string;
|
49 | ARROW_DOWN: string;
|
50 | DOWN: string;
|
51 | INSERT: string;
|
52 | DELETE: string;
|
53 | SEMICOLON: string;
|
54 | EQUALS: string;
|
55 |
|
56 | NUMPAD0: string; // number pad keys
|
57 | NUMPAD1: string;
|
58 | NUMPAD2: string;
|
59 | NUMPAD3: string;
|
60 | NUMPAD4: string;
|
61 | NUMPAD5: string;
|
62 | NUMPAD6: string;
|
63 | NUMPAD7: string;
|
64 | NUMPAD8: string;
|
65 | NUMPAD9: string;
|
66 | MULTIPLY: string;
|
67 | ADD: string;
|
68 | SEPARATOR: string;
|
69 | SUBTRACT: string;
|
70 | DECIMAL: string;
|
71 | DIVIDE: string;
|
72 |
|
73 | F1: string; // function keys
|
74 | F2: string;
|
75 | F3: string;
|
76 | F4: string;
|
77 | F5: string;
|
78 | F6: string;
|
79 | F7: string;
|
80 | F8: string;
|
81 | F9: string;
|
82 | F10: string;
|
83 | F11: string;
|
84 | F12: string;
|
85 |
|
86 | COMMAND: string; // Apple command key
|
87 | META: string; // alias for Windows key
|
88 |
|
89 | /**
|
90 | * Simulate pressing many keys at once in a 'chord'. Takes a sequence of
|
91 | * keys or strings, appends each of the values to a string,
|
92 | * and adds the chord termination key ({@link Key.NULL}) and returns
|
93 | * the resulting string.
|
94 | *
|
95 | * Note: when the low-level webdriver key handlers see Keys.NULL, active
|
96 | * modifier keys (CTRL/ALT/SHIFT/etc) release via a keyup event.
|
97 | *
|
98 | * @param {...string} var_args The key sequence to concatenate.
|
99 | * @return {string} The null-terminated key sequence.
|
100 | */
|
101 | chord(...var_args: Array<string|IKey>): string;
|
102 | }
|
103 |
|
104 | /**
|
105 | * Representations of pressable keys that aren't text. These are stored in
|
106 | * the Unicode PUA (Private Use Area) code points, 0xE000-0xF8FF. Refer to
|
107 | * http://www.google.com.au/search?&q=unicode+pua&btnG=Search
|
108 | *
|
109 | * @enum {string}
|
110 | */
|
111 | export const Key: IKey;
|
112 |
|
113 | export interface IDirection {
|
114 | x?: number|undefined;
|
115 | y?: number|undefined;
|
116 | duration?: number|undefined;
|
117 | origin?: Origin|WebElement|undefined;
|
118 | }
|
119 |
|
120 | export const INTERNAL_COMPUTE_OFFSET_SCRIPT: string;
|
121 |
|
122 | export class Device { constructor(type: string, id: string); }
|
123 |
|
124 | export class Pointer extends Device {}
|
125 | export class Keyboard extends Device {}
|
126 |
|
127 | /**
|
128 | * Class for defining sequences of complex user interactions. Each sequence
|
129 | * will not be executed until {@link #perform} is called.
|
130 | *
|
131 | * Example:
|
132 | *
|
133 | * new Actions(driver).
|
134 | * keyDown(Key.SHIFT).
|
135 | * click(element1).
|
136 | * click(element2).
|
137 | * dragAndDrop(element3, element4).
|
138 | * keyUp(Key.SHIFT).
|
139 | * perform();
|
140 | *
|
141 | */
|
142 | export class Actions {
|
143 | // region Constructors
|
144 |
|
145 | constructor(executor: Executor, options?: {async: boolean,
|
146 | bridge: boolean}|{async: boolean}|{bridge: boolean});
|
147 |
|
148 | // endregion
|
149 |
|
150 | // region Methods
|
151 | keyboard(): Keyboard;
|
152 | mouse(): Pointer;
|
153 | /**
|
154 | * Executes this action sequence.
|
155 | * @return {!Promise} A promise that will be resolved once
|
156 | * this sequence has completed.
|
157 | */
|
158 | clear(): Promise<void>;
|
159 |
|
160 | /**
|
161 | * Executes this action sequence.
|
162 | * @return {!Promise} A promise that will be resolved once
|
163 | * this sequence has completed.
|
164 | */
|
165 | perform(): Promise<void>;
|
166 |
|
167 | pause(duration?: number|Device, ...devices: Device[]): Actions;
|
168 |
|
169 | /**
|
170 | * Inserts an action to press a mouse button at the mouse's current location.
|
171 | * Defaults to `LEFT`.
|
172 | */
|
173 | press(button?: Button): Actions;
|
174 |
|
175 | /**
|
176 | * Inserts an action to release a mouse button at the mouse's current
|
177 | * location. Defaults to `LEFT`.
|
178 | */
|
179 | release(button?: Button): Actions;
|
180 |
|
181 | /**
|
182 | * Inserts an action for moving the mouse `x` and `y` pixels relative to the
|
183 | * specified `origin`. The `origin` may be defined as the mouse's
|
184 | * {@linkplain ./input.Origin.POINTER current position}, the
|
185 | * {@linkplain ./input.Origin.VIEWPORT viewport}, or the center of a specific
|
186 | * {@linkplain ./webdriver.WebElement WebElement}.
|
187 | *
|
188 | * You may adjust how long the remote end should take, in milliseconds, to
|
189 | * perform the move using the `duration` parameter (defaults to 100 ms).
|
190 | * The number of incremental move events generated over this duration is an
|
191 | * implementation detail for the remote end.
|
192 | *
|
193 | * Defaults to moving the mouse to the top-left
|
194 | * corner of the viewport over 100ms.
|
195 | */
|
196 | move(direction: IDirection): Actions;
|
197 |
|
198 | /**
|
199 | * Moves the mouse. The location to move to may be specified in terms of the
|
200 | * mouse's current location, an offset relative to the top-left corner of an
|
201 | * element, or an element (in which case the middle of the element is used).
|
202 | *
|
203 | * @param {(!./WebElement|{x: number, y: number})} location The
|
204 | * location to drag to, as either another WebElement or an offset in
|
205 | * pixels.
|
206 | * @param {{x: number, y: number}=} opt_offset If the target {@code location}
|
207 | * is defined as a {@link ./WebElement}, this parameter defines
|
208 | * an offset within that element. The offset should be specified in pixels
|
209 | * relative to the top-left corner of the element's bounding box. If
|
210 | * omitted, the element's center will be used as the target offset.
|
211 | * @return {!Actions} A self reference.
|
212 | */
|
213 | mouseMove(location: WebElement|ILocation, opt_offset?: ILocation): Actions;
|
214 |
|
215 | /**
|
216 | * Presses a mouse button. The mouse button will not be released until
|
217 | * {@link #mouseUp} is called, regardless of whether that call is made in this
|
218 | * sequence or another. The behavior for out-of-order events (e.g. mouseDown,
|
219 | * click) is undefined.
|
220 | *
|
221 | * If an element is provided, the mouse will first be moved to the center
|
222 | * of that element. This is equivalent to:
|
223 | *
|
224 | * sequence.mouseMove(element).mouseDown()
|
225 | *
|
226 | * Warning: this method currently only supports the left mouse button. See
|
227 | * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047).
|
228 | *
|
229 | * @param {(./WebElement|input.Button)=} opt_elementOrButton Either
|
230 | * the element to interact with or the button to click with.
|
231 | * Defaults to {@link input.Button.LEFT} if neither an element nor
|
232 | * button is specified.
|
233 | * @param {input.Button=} opt_button The button to use. Defaults to
|
234 | * {@link input.Button.LEFT}. Ignored if a button is provided as the
|
235 | * first argument.
|
236 | * @return {!Actions} A self reference.
|
237 | */
|
238 | mouseDown(opt_elementOrButton?: WebElement|string, opt_button?: string): Actions;
|
239 |
|
240 | /**
|
241 | * Releases a mouse button. Behavior is undefined for calling this function
|
242 | * without a previous call to {@link #mouseDown}.
|
243 | *
|
244 | * If an element is provided, the mouse will first be moved to the center
|
245 | * of that element. This is equivalent to:
|
246 | *
|
247 | * sequence.mouseMove(element).mouseUp()
|
248 | *
|
249 | * Warning: this method currently only supports the left mouse button. See
|
250 | * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047).
|
251 | *
|
252 | * @param {(./WebElement|input.Button)=} opt_elementOrButton Either
|
253 | * the element to interact with or the button to click with.
|
254 | * Defaults to {@link input.Button.LEFT} if neither an element nor
|
255 | * button is specified.
|
256 | * @param {input.Button=} opt_button The button to use. Defaults to
|
257 | * {@link input.Button.LEFT}. Ignored if a button is provided as the
|
258 | * first argument.
|
259 | * @return {!Actions} A self reference.
|
260 | */
|
261 | mouseUp(opt_elementOrButton?: WebElement|string, opt_button?: string): Actions;
|
262 |
|
263 | /**
|
264 | * Convenience function for performing a 'drag and drop' manuever. The target
|
265 | * element may be moved to the location of another element, or by an offset (in
|
266 | * pixels).
|
267 | */
|
268 | dragAndDrop(from: WebElement, to?: WebElement|{x?: number | string, y?: number|string}|null):
|
269 | Actions;
|
270 |
|
271 | /**
|
272 | * Clicks a mouse button.
|
273 | *
|
274 | * If an element is provided, the mouse will first be moved to the center
|
275 | * of that element. This is equivalent to:
|
276 | *
|
277 | * sequence.mouseMove(element).click()
|
278 | *
|
279 | * @param {(./WebElement|input.Button)=} opt_elementOrButton Either
|
280 | * the element to interact with or the button to click with.
|
281 | * Defaults to {@link input.Button.LEFT} if neither an element nor
|
282 | * button is specified.
|
283 | * @param {input.Button=} opt_button The button to use. Defaults to
|
284 | * {@link input.Button.LEFT}. Ignored if a button is provided as the
|
285 | * first argument.
|
286 | * @return {!Actions} A self reference.
|
287 | */
|
288 | click(opt_elementOrButton?: WebElement|string, opt_button?: string): Actions;
|
289 |
|
290 | /**
|
291 | * Double-clicks a mouse button.
|
292 | *
|
293 | * If an element is provided, the mouse will first be moved to the center of
|
294 | * that element. This is equivalent to:
|
295 | *
|
296 | * sequence.mouseMove(element).doubleClick()
|
297 | *
|
298 | * Warning: this method currently only supports the left mouse button. See
|
299 | * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047).
|
300 | *
|
301 | * @param {(./WebElement|input.Button)=} opt_elementOrButton Either
|
302 | * the element to interact with or the button to click with.
|
303 | * Defaults to {@link input.Button.LEFT} if neither an element nor
|
304 | * button is specified.
|
305 | * @param {input.Button=} opt_button The button to use. Defaults to
|
306 | * {@link input.Button.LEFT}. Ignored if a button is provided as the
|
307 | * first argument.
|
308 | * @return {!Actions} A self reference.
|
309 | */
|
310 | doubleClick(opt_elementOrButton?: WebElement|string, opt_button?: string): Actions;
|
311 |
|
312 | /**
|
313 | * Short-hand for performing a simple right-click (down/up) with the mouse.
|
314 | *
|
315 | * @param {./webdriver.WebElement=} element If specified, the mouse will
|
316 | * first be moved to the center of the element before performing the
|
317 | * click.
|
318 | * @return {!Actions} a self reference.
|
319 | */
|
320 | contextClick(opt_elementOrButton?: WebElement|string): Actions;
|
321 |
|
322 | /**
|
323 | * Performs a modifier key press. The modifier key is <em>not released</em>
|
324 | * until {@link #keyUp} or {@link #sendKeys} is called. The key press will be
|
325 | * targetted at the currently focused element.
|
326 | * @param {!Key} key The modifier key to push. Must be one of
|
327 | * {ALT, CONTROL, SHIFT, COMMAND, META}.
|
328 | * @return {!Actions} A self reference.
|
329 | * @throws {Error} If the key is not a valid modifier key.
|
330 | */
|
331 | keyDown(key: string): Actions;
|
332 |
|
333 | /**
|
334 | * Performs a modifier key release. The release is targetted at the currently
|
335 | * focused element.
|
336 | * @param {!Key} key The modifier key to release. Must be one of
|
337 | * {ALT, CONTROL, SHIFT, COMMAND, META}.
|
338 | * @return {!Actions} A self reference.
|
339 | * @throws {Error} If the key is not a valid modifier key.
|
340 | */
|
341 | keyUp(key: string): Actions;
|
342 |
|
343 | /**
|
344 | * Simulates typing multiple keys. Each modifier key encountered in the
|
345 | * sequence will not be released until it is encountered again. All key events
|
346 | * will be targeted at the currently focused element.
|
347 | *
|
348 | * @param {...(string|!input.Key|!Array<(string|!input.Key)>)} var_args
|
349 | * The keys to type.
|
350 | * @return {!Actions} A self reference.
|
351 | * @throws {Error} If the key is not a valid modifier key.
|
352 | */
|
353 | sendKeys(...var_args: Array<string|Promise<string>>): Actions;
|
354 |
|
355 | // endregion
|
356 | }
|