Deprecate keyPress, keyDown, keyUp in favor of pressKey.

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);
     }
 

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);
 

src/Element/NodeElement.php

@@ -305,37 +305,52 @@ 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));
     }
 
     /**
      * Pressed up 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 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;
+        }
+    }
 }

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');
 

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');