From 41ae2243664b92e0ad0de838d6cf1413bc1d9278 Mon Sep 17 00:00:00 2001 From: M Parker Date: Wed, 4 May 2022 17:31:33 -0400 Subject: [PATCH] Deprecate keyPress, keyDown, keyUp in favor of pressKey. --- src/Driver/CoreDriver.php | 11 ++++++++ src/Driver/DriverInterface.php | 15 ++++++++++ src/Element/NodeElement.php | 46 ++++++++++++++++++++++++++++--- tests/Driver/CoreDriverTest.php | 4 +++ tests/Element/NodeElementTest.php | 6 ++-- 5 files changed, 75 insertions(+), 7 deletions(-) diff --git a/src/Driver/CoreDriver.php b/src/Driver/CoreDriver.php index 9b4c04e43..0774c681b 100644 --- a/src/Driver/CoreDriver.php +++ b/src/Driver/CoreDriver.php @@ -393,11 +393,20 @@ public function blur($xpath) throw new UnsupportedDriverActionException('Mouse manipulations are not supported by %s', $this); } + /** + * {@inheritdoc} + */ + public function pressKey($xpath, $keys) + { + throw new UnsupportedDriverActionException('Keyboard manipulations are not supported by %s', $this); + } + /** * {@inheritdoc} */ public function keyPress($xpath, $char, $modifier = null) { + @trigger_error(sprintf('The method %s is deprecated as of 1.11 and will be removed in 2.0', __METHOD__), E_USER_DEPRECATED); throw new UnsupportedDriverActionException('Keyboard manipulations are not supported by %s', $this); } @@ -406,6 +415,7 @@ public function keyPress($xpath, $char, $modifier = null) */ public function keyDown($xpath, $char, $modifier = null) { + @trigger_error(sprintf('The method %s is deprecated as of 1.11 and will be removed in 2.0', __METHOD__), E_USER_DEPRECATED); throw new UnsupportedDriverActionException('Keyboard manipulations are not supported by %s', $this); } @@ -414,6 +424,7 @@ public function keyDown($xpath, $char, $modifier = null) */ public function keyUp($xpath, $char, $modifier = null) { + @trigger_error(sprintf('The method %s is deprecated as of 1.11 and will be removed in 2.0', __METHOD__), E_USER_DEPRECATED); throw new UnsupportedDriverActionException('Keyboard manipulations are not supported by %s', $this); } diff --git a/src/Driver/DriverInterface.php b/src/Driver/DriverInterface.php index 0eec66bc5..42034422d 100644 --- a/src/Driver/DriverInterface.php +++ b/src/Driver/DriverInterface.php @@ -518,6 +518,15 @@ public function focus($xpath); */ public function blur($xpath); + /** + * @param string $xpath + * @param string|array|int $keys a string to type ('PHP Hypertext Preprocessor'), a integer key code (88), or an array of keys to press in sequence (e.g.: ["\u{E008}", 'H', "\u{E001}", 'ello']). See https://w3c.github.io/webdriver/#keyboard-actions + * + * @throws UnsupportedDriverActionException When operation not supported by the driver + * @throws DriverException When the operation cannot be done + */ + public function pressKey($xpath, $keys); + /** * Presses specific keyboard key. * @@ -527,6 +536,8 @@ public function blur($xpath); * * @throws UnsupportedDriverActionException When operation not supported by the driver * @throws DriverException When the operation cannot be done + * + * @deprecated use pressKey($xpath, $keys) instead. */ public function keyPress($xpath, $char, $modifier = null); @@ -539,6 +550,8 @@ public function keyPress($xpath, $char, $modifier = null); * * @throws UnsupportedDriverActionException When operation not supported by the driver * @throws DriverException When the operation cannot be done + * + * @deprecated use pressKey($xpath, $keys) instead. */ public function keyDown($xpath, $char, $modifier = null); @@ -551,6 +564,8 @@ public function keyDown($xpath, $char, $modifier = null); * * @throws UnsupportedDriverActionException When operation not supported by the driver * @throws DriverException When the operation cannot be done + * + * @deprecated use pressKey($xpath, $keys) instead. */ public function keyUp($xpath, $char, $modifier = null); diff --git a/src/Element/NodeElement.php b/src/Element/NodeElement.php index 9aa186840..df9413083 100644 --- a/src/Element/NodeElement.php +++ b/src/Element/NodeElement.php @@ -305,26 +305,39 @@ public function blur() $this->getDriver()->blur($this->getXpath()); } + /** + * Press one or more keyboard keys on an element. + * + * @param string|int|array $keys a string to type ('PHP Hypertext Preprocessor'), a integer key code (88), or an array of keys to press in sequence (e.g.: ["\u{E008}", 'H', "\u{E001}", 'ello']). See https://w3c.github.io/webdriver/#keyboard-actions + */ + public function pressKey($keys) { + $this->getDriver()->pressKey($this->getXpath(), $keys); + } + /** * Presses specific keyboard key. * * @param string|int $char could be either char ('b') or char-code (98) * @param string|null $modifier keyboard modifier (could be 'ctrl', 'alt', 'shift' or 'meta') + * + * @deprecated use pressKey($keys) instead. */ public function keyPress($char, $modifier = null) { - $this->getDriver()->keyPress($this->getXpath(), $char, $modifier); + $this->pressKey($this->wrapCharWithModifier($char, $modifier)); } /** * Pressed down specific keyboard key. * * @param string|int $char could be either char ('b') or char-code (98) - * @param string|null $modifier keyboard modifier (could be 'ctrl', 'alt', 'shift' or 'meta') + * @param string|null $modifier keyboard modifier (could be 'ctrl', 'alt', 'shift' or 'meta')' + * + * @deprecated use pressKey($keys) instead. */ public function keyDown($char, $modifier = null) { - $this->getDriver()->keyDown($this->getXpath(), $char, $modifier); + $this->pressKey($this->wrapCharWithModifier($char, $modifier)); } /** @@ -332,10 +345,12 @@ public function keyDown($char, $modifier = null) * * @param string|int $char could be either char ('b') or char-code (98) * @param string|null $modifier keyboard modifier (could be 'ctrl', 'alt', 'shift' or 'meta') + * + * @deprecated use pressKey($keys) instead. */ public function keyUp($char, $modifier = null) { - $this->getDriver()->keyUp($this->getXpath(), $char, $modifier); + $this->pressKey($this->wrapCharWithModifier($char, $modifier)); } /** @@ -347,4 +362,27 @@ public function submit() { $this->getDriver()->submitForm($this->getXpath()); } + + /** + * Polyfill to convert from deprecated keyPress(), keyDown(), keyUp() parameters to pressKey() parameters. + * + * @param string|int $char could be either char ('b') or char-code (98) + * @param string|null $modifier keyboard modifier (could be 'ctrl', 'alt', 'shift' or 'meta') + * @return string|int|array a $keys parameter that pressKey() can parse + */ + private function wrapCharWithModifier($char, $modifier = null) + { + switch ($modifier) { + case 'ctrl': + return ["\u{E009}", $char, "\u{E001}"]; + case 'alt': + return ["\u{E00A}", $char, "\u{E001}"]; + case 'shift': + return ["\u{E008}", $char, "\u{E001}"]; + case 'meta': + return ["\u{E03D}", $char, "\u{E001}"]; + default: + return $char; + } + } } diff --git a/tests/Driver/CoreDriverTest.php b/tests/Driver/CoreDriverTest.php index f4a597886..ab1bf83c1 100644 --- a/tests/Driver/CoreDriverTest.php +++ b/tests/Driver/CoreDriverTest.php @@ -64,6 +64,10 @@ public function testInterfaceMethods(\ReflectionMethod $method) if ('setSession' === $method->getName()) { return; // setSession is actually implemented, so we don't expect an exception here. } + if (in_array($method->getName(), ['keyPress', 'keyDown', 'keyUp'])) { + return; // Skip deprecated methods in the driver + } + $driver = $this->getMockForAbstractClass('Behat\Mink\Driver\CoreDriver'); diff --git a/tests/Element/NodeElementTest.php b/tests/Element/NodeElementTest.php index 0766d7a3d..50e74c728 100644 --- a/tests/Element/NodeElementTest.php +++ b/tests/Element/NodeElementTest.php @@ -505,7 +505,7 @@ public function testKeyPress() $this->driver ->expects($this->once()) - ->method('keyPress') + ->method('pressKey') ->with('elem', 'key'); $node->keyPress('key'); @@ -517,7 +517,7 @@ public function testKeyDown() $this->driver ->expects($this->once()) - ->method('keyDown') + ->method('pressKey') ->with('elem', 'key'); $node->keyDown('key'); @@ -529,7 +529,7 @@ public function testKeyUp() $this->driver ->expects($this->once()) - ->method('keyUp') + ->method('pressKey') ->with('elem', 'key'); $node->keyUp('key');