Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Deprecate keyPress, keyDown, keyUp in favor of pressKey. #831

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

mparker17
Copy link

Problem / motivation

in #828, @stof said that "the [driver methods] that should actually be deprecated are the separate keydown, keypress and keyup methods in favor of a single pressKey method to match what is actually possible in browsers."

Proposed resolution

  • Deprecate DriverInterface::keyDown(), DriverInterface::keyPress(), and DriverInterface::keyUp() in favor of a new DriverInterface::pressKey()
  • Deprecate NodeElement::keyDown(), NodeElement::keyPress(), and NodeElement::keyUp() in favor of a new NodeElement::pressKey()

Notes

I modelled the DriverInterface::pressKey() method after php-webdriver/php-webdriver's \Facebook\WebDriver\Remote\RemoteKeyboard::sendKeys()

@codecov
Copy link

codecov bot commented May 4, 2022

Codecov Report

Merging #831 (41ae224) into master (19e5890) will decrease coverage by 1.26%.
The diff coverage is 68.18%.

@@             Coverage Diff              @@
##             master     #831      +/-   ##
============================================
- Coverage     98.47%   97.20%   -1.27%     
- Complexity      345      353       +8     
============================================
  Files            23       23              
  Lines           983     1002      +19     
============================================
+ Hits            968      974       +6     
- Misses           15       28      +13     
Impacted Files Coverage Δ
src/Driver/CoreDriver.php 92.30% <40.00%> (-7.70%) ⬇️
src/Element/NodeElement.php 95.87% <76.47%> (-4.13%) ⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 19e5890...41ae224. Read the comment docs.

/**
* {@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);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is triggering a deprecation notice from a method, that throws an exception a good idea?

Maybe we should trigger a deprecation notice in driver sub-classes, where this method is completely replaced?


The same goes for other similar places.

*
* @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) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changing an interface is a BC break.

*/
public function keyPress($char, $modifier = null)
{
$this->getDriver()->keyPress($this->getXpath(), $char, $modifier);
$this->pressKey($this->wrapCharWithModifier($char, $modifier));
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding a @deprecated tag alone in the DocBlock won't help much, but having a matching deprecation notice triggering code will.


The same goes for other similar places in this class.

*/
public function keyPress($char, $modifier = null)
{
$this->getDriver()->keyPress($this->getXpath(), $char, $modifier);
$this->pressKey($this->wrapCharWithModifier($char, $modifier));
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

keyPress, keyDown and keyUp are not something that can be implemented on top of pressKey, which is the priammy reason to deprecate them.

/**
* 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

our own API should not be based on the Webdriver representation of modifier keys, as that might not fit other drivers.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants