keyboard_types/
webdriver.rs

1//! Keyboard related WebDriver functionality.
2//!
3//! The low-level [`KeyInputState::dispatch_keydown`] and
4//! [`KeyInputState::dispatch_keyup`] API creates keyboard events
5//! from WebDriver codes. It is used in the *Perform Actions* API.
6//!
7//! ```rust
8//! # extern crate keyboard_types;
9//! # use keyboard_types::*;
10//! # use keyboard_types::webdriver::*;
11//! let mut state = KeyInputState::new();
12//! let mut keyboard_event = state.dispatch_keydown('a');
13//! assert_eq!(keyboard_event.state, KeyState::Down);
14//! assert_eq!(keyboard_event.key, Key::Character("a".to_owned()));
15//! assert_eq!(keyboard_event.code, Code::KeyA);
16//!
17//! // The `\u{E029}` code is the WebDriver id for the Numpad divide key.
18//! keyboard_event = state.dispatch_keydown('\u{E050}');
19//! assert_eq!(keyboard_event.key, Key::Named(NamedKey::Shift));
20//! assert_eq!(keyboard_event.code, Code::ShiftRight);
21//! assert_eq!(keyboard_event.location, Location::Right);
22//!
23//! keyboard_event = state.dispatch_keyup('\u{E050}').expect("key is released");
24//! keyboard_event = state.dispatch_keyup('a').expect("key is released");
25//! ```
26//!
27//! The higher level [`send_keys`] function is used for the *Element Send Keys*
28//! WebDriver API. It accepts a string and returns a sequence of [`KeyboardEvent`]
29//! and [`CompositionEvent`] values.
30//!
31//! ```rust
32//! # extern crate keyboard_types;
33//! # use keyboard_types::*;
34//! # use keyboard_types::webdriver::*;
35//! let events = send_keys("Hello world!\u{E006}");
36//! println!("{:#?}", events);
37//!
38//! let events = send_keys("A\u{0308}");
39//! println!("{:#?}", events);
40//! ```
41//!
42//! Specification: <https://w3c.github.io/webdriver/>
43
44use std::collections::HashSet;
45
46use unicode_segmentation::UnicodeSegmentation;
47
48use crate::{first_char, NamedKey};
49use crate::{Code, Key, KeyState, KeyboardEvent, Location, Modifiers};
50use crate::{CompositionEvent, CompositionState};
51
52// Spec: <https://w3c.github.io/webdriver/#keyboard-actions>
53// normalised (sic) as in british spelling
54fn normalised_key_value(raw_key: char) -> Key {
55    match raw_key {
56        '\u{E000}' => Key::Named(NamedKey::Unidentified),
57        '\u{E001}' => Key::Named(NamedKey::Cancel),
58        '\u{E002}' => Key::Named(NamedKey::Help),
59        '\u{E003}' => Key::Named(NamedKey::Backspace),
60        '\u{E004}' => Key::Named(NamedKey::Tab),
61        '\u{E005}' => Key::Named(NamedKey::Clear),
62        // FIXME: spec says "Return"
63        '\u{E006}' => Key::Named(NamedKey::Enter),
64        '\u{E007}' => Key::Named(NamedKey::Enter),
65        '\u{E008}' => Key::Named(NamedKey::Shift),
66        '\u{E009}' => Key::Named(NamedKey::Control),
67        '\u{E00A}' => Key::Named(NamedKey::Alt),
68        '\u{E00B}' => Key::Named(NamedKey::Pause),
69        '\u{E00C}' => Key::Named(NamedKey::Escape),
70        '\u{E00D}' => Key::Character(" ".to_string()),
71        '\u{E00E}' => Key::Named(NamedKey::PageUp),
72        '\u{E00F}' => Key::Named(NamedKey::PageDown),
73        '\u{E010}' => Key::Named(NamedKey::End),
74        '\u{E011}' => Key::Named(NamedKey::Home),
75        '\u{E012}' => Key::Named(NamedKey::ArrowLeft),
76        '\u{E013}' => Key::Named(NamedKey::ArrowUp),
77        '\u{E014}' => Key::Named(NamedKey::ArrowRight),
78        '\u{E015}' => Key::Named(NamedKey::ArrowDown),
79        '\u{E016}' => Key::Named(NamedKey::Insert),
80        '\u{E017}' => Key::Named(NamedKey::Delete),
81        '\u{E018}' => Key::Character(";".to_string()),
82        '\u{E019}' => Key::Character("=".to_string()),
83        '\u{E01A}' => Key::Character("0".to_string()),
84        '\u{E01B}' => Key::Character("1".to_string()),
85        '\u{E01C}' => Key::Character("2".to_string()),
86        '\u{E01D}' => Key::Character("3".to_string()),
87        '\u{E01E}' => Key::Character("4".to_string()),
88        '\u{E01F}' => Key::Character("5".to_string()),
89        '\u{E020}' => Key::Character("6".to_string()),
90        '\u{E021}' => Key::Character("7".to_string()),
91        '\u{E022}' => Key::Character("8".to_string()),
92        '\u{E023}' => Key::Character("9".to_string()),
93        '\u{E024}' => Key::Character("*".to_string()),
94        '\u{E025}' => Key::Character("+".to_string()),
95        '\u{E026}' => Key::Character(",".to_string()),
96        '\u{E027}' => Key::Character("-".to_string()),
97        '\u{E028}' => Key::Character(".".to_string()),
98        '\u{E029}' => Key::Character("/".to_string()),
99        '\u{E031}' => Key::Named(NamedKey::F1),
100        '\u{E032}' => Key::Named(NamedKey::F2),
101        '\u{E033}' => Key::Named(NamedKey::F3),
102        '\u{E034}' => Key::Named(NamedKey::F4),
103        '\u{E035}' => Key::Named(NamedKey::F5),
104        '\u{E036}' => Key::Named(NamedKey::F6),
105        '\u{E037}' => Key::Named(NamedKey::F7),
106        '\u{E038}' => Key::Named(NamedKey::F8),
107        '\u{E039}' => Key::Named(NamedKey::F9),
108        '\u{E03A}' => Key::Named(NamedKey::F10),
109        '\u{E03B}' => Key::Named(NamedKey::F11),
110        '\u{E03C}' => Key::Named(NamedKey::F12),
111        '\u{E03D}' => Key::Named(NamedKey::Meta),
112        '\u{E040}' => Key::Named(NamedKey::ZenkakuHankaku),
113        '\u{E050}' => Key::Named(NamedKey::Shift),
114        '\u{E051}' => Key::Named(NamedKey::Control),
115        '\u{E052}' => Key::Named(NamedKey::Alt),
116        '\u{E053}' => Key::Named(NamedKey::Meta),
117        '\u{E054}' => Key::Named(NamedKey::PageUp),
118        '\u{E055}' => Key::Named(NamedKey::PageDown),
119        '\u{E056}' => Key::Named(NamedKey::End),
120        '\u{E057}' => Key::Named(NamedKey::Home),
121        '\u{E058}' => Key::Named(NamedKey::ArrowLeft),
122        '\u{E059}' => Key::Named(NamedKey::ArrowUp),
123        '\u{E05A}' => Key::Named(NamedKey::ArrowRight),
124        '\u{E05B}' => Key::Named(NamedKey::ArrowDown),
125        '\u{E05C}' => Key::Named(NamedKey::Insert),
126        '\u{E05D}' => Key::Named(NamedKey::Delete),
127        _ => Key::Character(raw_key.to_string()),
128    }
129}
130
131/// Spec: <https://w3c.github.io/webdriver/#dfn-code>
132fn code(raw_key: char) -> Code {
133    match raw_key {
134        '`' | '~' => Code::Backquote,
135        '\\' | '|' => Code::Backslash,
136        '\u{E003}' => Code::Backspace,
137        '[' | '{' => Code::BracketLeft,
138        ']' | '}' => Code::BracketRight,
139        ',' | '<' => Code::Comma,
140        '0' | ')' => Code::Digit0,
141        '1' | '!' => Code::Digit1,
142        '2' | '@' => Code::Digit2,
143        '3' | '#' => Code::Digit3,
144        '4' | '$' => Code::Digit4,
145        '5' | '%' => Code::Digit5,
146        '6' | '^' => Code::Digit6,
147        '7' | '&' => Code::Digit7,
148        '8' | '*' => Code::Digit8,
149        '9' | '(' => Code::Digit9,
150        '=' | '+' => Code::Equal,
151        // FIXME: spec has '<' | '>' => Code::IntlBackslash,
152        'a' | 'A' => Code::KeyA,
153        'b' | 'B' => Code::KeyB,
154        'c' | 'C' => Code::KeyC,
155        'd' | 'D' => Code::KeyD,
156        'e' | 'E' => Code::KeyE,
157        'f' | 'F' => Code::KeyF,
158        'g' | 'G' => Code::KeyG,
159        'h' | 'H' => Code::KeyH,
160        'i' | 'I' => Code::KeyI,
161        'j' | 'J' => Code::KeyJ,
162        'k' | 'K' => Code::KeyK,
163        'l' | 'L' => Code::KeyL,
164        'm' | 'M' => Code::KeyM,
165        'n' | 'N' => Code::KeyN,
166        'o' | 'O' => Code::KeyO,
167        'p' | 'P' => Code::KeyP,
168        'q' | 'Q' => Code::KeyQ,
169        'r' | 'R' => Code::KeyR,
170        's' | 'S' => Code::KeyS,
171        't' | 'T' => Code::KeyT,
172        'u' | 'U' => Code::KeyU,
173        'v' | 'V' => Code::KeyV,
174        'w' | 'W' => Code::KeyW,
175        'x' | 'X' => Code::KeyX,
176        'y' | 'Y' => Code::KeyY,
177        'z' | 'Z' => Code::KeyZ,
178        '-' | '_' => Code::Minus,
179        '.' | '>' => Code::Period,
180        '\'' | '"' => Code::Quote,
181        ';' | ':' => Code::Semicolon,
182        '/' | '?' => Code::Slash,
183        '\u{E00A}' => Code::AltLeft,
184        '\u{E052}' => Code::AltRight,
185        '\u{E009}' => Code::ControlLeft,
186        '\u{E051}' => Code::ControlRight,
187        '\u{E006}' => Code::Enter,
188        // FIXME: spec says "OSLeft"
189        '\u{E03D}' => Code::MetaLeft,
190        // FIXME: spec says "OSRight"
191        '\u{E053}' => Code::MetaRight,
192        '\u{E008}' => Code::ShiftLeft,
193        '\u{E050}' => Code::ShiftRight,
194        ' ' | '\u{E00D}' => Code::Space,
195        '\u{E004}' => Code::Tab,
196        '\u{E017}' => Code::Delete,
197        '\u{E010}' => Code::End,
198        '\u{E002}' => Code::Help,
199        '\u{E011}' => Code::Home,
200        '\u{E016}' => Code::Insert,
201        // FIXME: spec says '\u{E01E}' => Code::PageDown, which is Numpad 4
202        '\u{E00F}' => Code::PageDown,
203        // FIXME: spec says '\u{E01F}' => Code::PageUp, which is Numpad 5
204        '\u{E00E}' => Code::PageUp,
205        '\u{E015}' => Code::ArrowDown,
206        '\u{E012}' => Code::ArrowLeft,
207        '\u{E014}' => Code::ArrowRight,
208        '\u{E013}' => Code::ArrowUp,
209        '\u{E00C}' => Code::Escape,
210        '\u{E031}' => Code::F1,
211        '\u{E032}' => Code::F2,
212        '\u{E033}' => Code::F3,
213        '\u{E034}' => Code::F4,
214        '\u{E035}' => Code::F5,
215        '\u{E036}' => Code::F6,
216        '\u{E037}' => Code::F7,
217        '\u{E038}' => Code::F8,
218        '\u{E039}' => Code::F9,
219        '\u{E03A}' => Code::F10,
220        '\u{E03B}' => Code::F11,
221        '\u{E03C}' => Code::F12,
222        '\u{E01A}' | '\u{E05C}' => Code::Numpad0,
223        '\u{E01B}' | '\u{E056}' => Code::Numpad1,
224        '\u{E01C}' | '\u{E05B}' => Code::Numpad2,
225        '\u{E01D}' | '\u{E055}' => Code::Numpad3,
226        '\u{E01E}' | '\u{E058}' => Code::Numpad4,
227        '\u{E01F}' => Code::Numpad5,
228        '\u{E020}' | '\u{E05A}' => Code::Numpad6,
229        '\u{E021}' | '\u{E057}' => Code::Numpad7,
230        '\u{E022}' | '\u{E059}' => Code::Numpad8,
231        '\u{E023}' | '\u{E054}' => Code::Numpad9,
232        // FIXME: spec says uE024
233        '\u{E025}' => Code::NumpadAdd,
234        '\u{E026}' => Code::NumpadComma,
235        '\u{E028}' | '\u{E05D}' => Code::NumpadDecimal,
236        '\u{E029}' => Code::NumpadDivide,
237        '\u{E007}' => Code::NumpadEnter,
238        '\u{E024}' => Code::NumpadMultiply,
239        // FIXME: spec says uE026
240        '\u{E027}' => Code::NumpadSubtract,
241        _ => Code::Unidentified,
242    }
243}
244
245fn is_shifted_character(raw_key: char) -> bool {
246    matches!(
247        raw_key,
248        '~' | '|'
249            | '{'
250            | '}'
251            | '<'
252            | ')'
253            | '!'
254            | '@'
255            | '#'
256            | '$'
257            | '%'
258            | '^'
259            | '&'
260            | '*'
261            | '('
262            | '+'
263            | '>'
264            | '_'
265            | '\"'
266            | ':'
267            | '?'
268            | '\u{E00D}'
269            | '\u{E05C}'
270            | '\u{E056}'
271            | '\u{E05B}'
272            | '\u{E055}'
273            | '\u{E058}'
274            | '\u{E05A}'
275            | '\u{E057}'
276            | '\u{E059}'
277            | '\u{E054}'
278            | '\u{E05D}'
279            | 'A'..='Z'
280    )
281}
282
283fn key_location(raw_key: char) -> Location {
284    match raw_key {
285        '\u{E007}'..='\u{E00A}' => Location::Left,
286        '\u{E01A}'..='\u{E029}' => Location::Numpad,
287        '\u{E03D}' => Location::Left,
288        '\u{E050}'..='\u{E053}' => Location::Right,
289        '\u{E054}'..='\u{E05D}' => Location::Numpad,
290        _ => Location::Standard,
291    }
292}
293
294fn get_modifier(key: &Key) -> Modifiers {
295    match key {
296        Key::Named(NamedKey::Alt) => Modifiers::ALT,
297        Key::Named(NamedKey::Shift) => Modifiers::SHIFT,
298        Key::Named(NamedKey::Control) => Modifiers::CONTROL,
299        Key::Named(NamedKey::Meta) => Modifiers::META,
300        _ => Modifiers::empty(),
301    }
302}
303
304/// Store pressed keys and modifiers.
305///
306/// Spec: <https://w3c.github.io/webdriver/#dfn-key-input-state>
307#[derive(Clone, Debug, Default)]
308#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
309pub struct KeyInputState {
310    pressed: HashSet<Key>,
311    modifiers: Modifiers,
312}
313
314impl KeyInputState {
315    /// New state without any keys or modifiers pressed.
316    ///
317    /// Same as the default value.
318    pub fn new() -> KeyInputState {
319        KeyInputState::default()
320    }
321
322    /// Get a keyboard-keydown event from a WebDriver key value.
323    ///
324    /// Stores that the key is pressed in the state object.
325    ///
326    /// The input cancel list is not implemented here but can be emulated
327    /// by adding the `raw_key` value with a `keyUp` action to a list
328    /// before executing this function.
329    ///
330    /// Specification: <https://w3c.github.io/webdriver/#dfn-dispatch-a-keydown-action>
331    pub fn dispatch_keydown(&mut self, raw_key: char) -> KeyboardEvent {
332        let key = normalised_key_value(raw_key);
333        let repeat = self.pressed.contains(&key);
334        let code = code(raw_key);
335        let location = key_location(raw_key);
336        self.modifiers.insert(get_modifier(&key));
337        self.pressed.insert(key.clone());
338        KeyboardEvent {
339            state: KeyState::Down,
340            key,
341            code,
342            location,
343            modifiers: self.modifiers,
344            repeat,
345            is_composing: false,
346        }
347    }
348
349    /// Get a keyboard-keyup event from a WebDriver key value.
350    ///
351    /// Updates state. Returns `None` if the key is not listed as pressed.
352    ///
353    /// Specification: <https://w3c.github.io/webdriver/#dfn-dispatch-a-keyup-action>
354    pub fn dispatch_keyup(&mut self, raw_key: char) -> Option<KeyboardEvent> {
355        let key = normalised_key_value(raw_key);
356        if !self.pressed.contains(&key) {
357            return None;
358        }
359        let code = code(raw_key);
360        let location = key_location(raw_key);
361        self.modifiers.remove(get_modifier(&key));
362        self.pressed.remove(&key);
363        Some(KeyboardEvent {
364            state: KeyState::Up,
365            key,
366            code,
367            location,
368            modifiers: self.modifiers,
369            repeat: false,
370            is_composing: false,
371        })
372    }
373
374    fn clear(&mut self, undo_actions: &mut HashSet<char>, result: &mut Vec<Event>) {
375        let mut actions: Vec<_> = undo_actions.drain().collect();
376        actions.sort_unstable();
377        for action in actions {
378            result.push(self.dispatch_keyup(action).unwrap().into());
379        }
380        assert!(undo_actions.is_empty());
381    }
382
383    fn dispatch_typeable(&mut self, text: &mut String, result: &mut Vec<Event>) {
384        for character in text.chars() {
385            let shifted = self.modifiers.contains(Modifiers::SHIFT);
386            if is_shifted_character(character) && !shifted {
387                // dispatch left shift down
388                result.push(self.dispatch_keydown('\u{E008}').into());
389            }
390            if !is_shifted_character(character) && shifted {
391                // dispatch left shift up
392                result.push(self.dispatch_keyup('\u{E008}').unwrap().into());
393            }
394            result.push(self.dispatch_keydown(character).into());
395            result.push(self.dispatch_keyup(character).unwrap().into());
396        }
397        text.clear();
398    }
399}
400
401/// Either a [`KeyboardEvent`] or a [`CompositionEvent`].
402///
403/// Returned by the [`send_keys`] function.
404#[derive(Clone, Eq, PartialEq, Hash, Debug, PartialOrd, Ord)]
405#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
406pub enum Event {
407    Keyboard(KeyboardEvent),
408    Composition(CompositionEvent),
409}
410
411impl From<KeyboardEvent> for Event {
412    fn from(v: KeyboardEvent) -> Event {
413        Event::Keyboard(v)
414    }
415}
416
417impl From<CompositionEvent> for Event {
418    fn from(v: CompositionEvent) -> Event {
419        Event::Composition(v)
420    }
421}
422
423/// Compute the events resulting from a WebDriver *Element Send Keys* command.
424///
425/// Spec: <https://w3c.github.io/webdriver/#element-send-keys>
426pub fn send_keys(text: &str) -> Vec<Event> {
427    #[allow(deprecated)]
428    fn is_modifier(text: &str) -> bool {
429        if text.chars().count() != 1 {
430            return false;
431        }
432        // values from <https://www.w3.org/TR/uievents-key/#keys-modifier>
433        matches!(
434            normalised_key_value(first_char(text)),
435            Key::Named(
436                NamedKey::Alt
437                    | NamedKey::AltGraph
438                    | NamedKey::CapsLock
439                    | NamedKey::Control
440                    | NamedKey::Fn
441                    | NamedKey::FnLock
442                    | NamedKey::Meta
443                    | NamedKey::NumLock
444                    | NamedKey::ScrollLock
445                    | NamedKey::Shift
446                    | NamedKey::Symbol
447                    | NamedKey::SymbolLock
448                    | NamedKey::Hyper
449                    | NamedKey::Super
450            )
451        )
452    }
453
454    /// Spec: <https://w3c.github.io/webdriver/#dfn-typeable>
455    fn is_typeable(text: &str) -> bool {
456        text.chars().count() == 1
457    }
458
459    let mut result = Vec::new();
460    let mut typeable_text = String::new();
461    let mut state = KeyInputState::new();
462    let mut undo_actions = HashSet::new();
463    for cluster in UnicodeSegmentation::graphemes(text, true) {
464        match cluster {
465            "\u{E000}" => {
466                state.dispatch_typeable(&mut typeable_text, &mut result);
467                state.clear(&mut undo_actions, &mut result);
468            }
469            s if is_modifier(s) => {
470                state.dispatch_typeable(&mut typeable_text, &mut result);
471                let raw_modifier = first_char(s);
472                result.push(state.dispatch_keydown(raw_modifier).into());
473                undo_actions.insert(raw_modifier);
474            }
475            s if is_typeable(s) => typeable_text.push_str(s),
476            s => {
477                state.dispatch_typeable(&mut typeable_text, &mut result);
478                // FIXME: Spec says undefined instead of empty string
479                result.push(
480                    CompositionEvent {
481                        state: CompositionState::Start,
482                        data: String::new(),
483                    }
484                    .into(),
485                );
486                result.push(
487                    CompositionEvent {
488                        state: CompositionState::Update,
489                        data: s.to_owned(),
490                    }
491                    .into(),
492                );
493                result.push(
494                    CompositionEvent {
495                        state: CompositionState::End,
496                        data: s.to_owned(),
497                    }
498                    .into(),
499                );
500            }
501        }
502    }
503    state.dispatch_typeable(&mut typeable_text, &mut result);
504    state.clear(&mut undo_actions, &mut result);
505    result
506}
keyboard_types/webdriver.rs

keyboard_types/
webdriver.rs
