diff --git a/tests/acceptance/features/core/Actor.php b/tests/acceptance/features/core/Actor.php index 0e45aea3353..a87ccfb7737 100644 --- a/tests/acceptance/features/core/Actor.php +++ b/tests/acceptance/features/core/Actor.php @@ -42,6 +42,11 @@ * exception is thrown if the element is not found, and, optionally, it is * possible to try again to find the element several times before giving up. * + * The returned object is also a wrapper over the element itself that + * automatically handles common causes of failed commands, like clicking on a + * hidden element; in this case, the wrapper would wait for the element to be + * visible up to the timeout set to find the element. + * * The amount of time to wait before giving up is specified in each call to * find(). However, a general multiplier to be applied to every timeout can be * set using setFindTimeoutMultiplier(); this makes possible to retry longer @@ -150,6 +155,10 @@ class Actor { * before retrying is half a second. If the timeout is not 0 it will be * affected by the multiplier set using setFindTimeoutMultiplier(), if any. * + * When found, the element is returned wrapped in an ElementWrapper; the + * ElementWrapper handles common causes of failures when executing commands + * in an element, like clicking on a hidden element. + * * In any case, if the element, or its ancestors, can not be found a * NoSuchElementException is thrown. * @@ -158,7 +167,7 @@ class Actor { * most for the element to appear. * @param float $timeoutStep the number of seconds (decimals allowed) to * wait before trying to find the element again. - * @return \Behat\Mink\Element\Element the element found. + * @return ElementWrapper an ElementWrapper object for the element. * @throws NoSuchElementException if the element, or its ancestor, can not * be found. */ @@ -167,7 +176,7 @@ class Actor { $elementFinder = new ElementFinder($this->session, $elementLocator, $timeout, $timeoutStep); - return $elementFinder->find(); + return new ElementWrapper($elementFinder); } /** diff --git a/tests/acceptance/features/core/ElementFinder.php b/tests/acceptance/features/core/ElementFinder.php index 9e1457a6864..d075e9fe660 100644 --- a/tests/acceptance/features/core/ElementFinder.php +++ b/tests/acceptance/features/core/ElementFinder.php @@ -158,6 +158,35 @@ class ElementFinder { $this->timeoutStep = $timeoutStep; } + /** + * Returns the description of the element to find. + * + * @return string the description of the element to find. + */ + public function getDescription() { + return $this->elementLocator->getDescription(); + } + + /** + * Returns the timeout. + * + * @return float the number of seconds (decimals allowed) to wait at most + * for the element to appear. + */ + public function getTimeout() { + return $this->timeout; + } + + /** + * Returns the timeout step. + * + * @return float the number of seconds (decimals allowed) to wait before + * trying to find the element again. + */ + public function getTimeoutStep() { + return $this->timeoutStep; + } + /** * Finds an element using the parameters set in the constructor of this * ElementFinder. diff --git a/tests/acceptance/features/core/ElementWrapper.php b/tests/acceptance/features/core/ElementWrapper.php new file mode 100644 index 00000000000..6b730903f6c --- /dev/null +++ b/tests/acceptance/features/core/ElementWrapper.php @@ -0,0 +1,275 @@ +. + * + */ + +/** + * Wrapper to automatically handle failed commands on Mink elements. + * + * Commands executed on Mink elements may fail for several reasons. The + * ElementWrapper frees the caller of the commands from handling the most common + * reasons of failure. + * + * StaleElementReference exceptions are thrown when the command is executed on + * an element that is no longer attached to the DOM. This can happen even in + * a chained call like "$actor->find($locator)->click()"; in the milliseconds + * between finding the element and clicking it the element could have been + * removed from the page (for example, if a previous interaction with the page + * started an asynchronous update of the DOM). Every command executed through + * the ElementWrapper is guarded against StaleElementReference exceptions; if + * the element is stale it is found again using the same parameters to find it + * in the first place. + * + * ElementNotVisible exceptions are thrown when the command requires the element + * to be visible but the element is not. Finding an element only guarantees that + * (at that time) the element is attached to the DOM, but it does not provide + * any guarantee regarding its visibility. Due to that, a call like + * "$actor->find($locator)->click()" can fail if the element was hidden and + * meant to be made visible by a previous interaction with the page, but that + * interaction triggered an asynchronous update that was not finished when the + * click command is executed. All commands executed through the ElementWrapper + * that require the element to be visible are guarded against ElementNotVisible + * exceptions; if the element is not visible it is waited for it to be visible + * up to the timeout set to find it. + * + * Despite the automatic handling it is possible for the commands to throw those + * exceptions when they are executed again; this class does not handle cases + * like an element becoming stale several times in a row (uncommon) or an + * element not becoming visible before the timeout expires (which would mean + * that the timeout is too short or that the test has to, indeed, fail). + * + * If needed, automatically handling failed commands can be disabled calling + * "doNotHandleFailedCommands()"; as it returns the ElementWrapper it can be + * chained with the command to execute (but note that automatically handling + * failed commands will still be disabled if further commands are executed on + * the ElementWrapper). + */ +class ElementWrapper { + + /** + * @var ElementFinder + */ + private $elementFinder; + + /** + * @var \Behat\Mink\Element\Element + */ + private $element; + + /** + * @param boolean + */ + private $handleFailedCommands; + + /** + * Creates a new ElementWrapper. + * + * The wrapped element is found in the constructor itself using the + * ElementFinder. + * + * @param ElementFinder $elementFinder the command object to find the + * wrapped element. + * @throws NoSuchElementException if the element, or its ancestor, can not + * be found. + */ + public function __construct(ElementFinder $elementFinder) { + $this->elementFinder = $elementFinder; + $this->element = $elementFinder->find(); + $this->handleFailedCommands = true; + } + + /** + * Returns the raw Mink element. + * + * @return \Behat\Mink\Element\Element the wrapped element. + */ + public function getWrappedElement() { + return $element; + } + + /** + * Prevents the automatic handling of failed commands. + * + * @return ElementWrapper this ElementWrapper. + */ + public function doNotHandleFailedCommands() { + $this->handleFailedCommands = false; + + return $this; + } + + /** + * Returns whether the wrapped element is visible or not. + * + * @return boolbean true if the wrapped element is visible, false otherwise. + */ + public function isVisible() { + $commandCallback = function() { + return $this->element->isVisible(); + }; + return $this->executeCommand($commandCallback, "visibility could not be got"); + } + + /** + * Returns the text of the wrapped element. + * + * If the wrapped element is not visible the returned text is an empty + * string. + * + * @return string the text of the wrapped element, or an empty string if it + * is not visible. + */ + public function getText() { + $commandCallback = function() { + return $this->element->getText(); + }; + return $this->executeCommand($commandCallback, "text could not be got"); + } + + /** + * Returns the value of the wrapped element. + * + * The value can be got even if the wrapped element is not visible. + * + * @return string the value of the wrapped element. + */ + public function getValue() { + $commandCallback = function() { + return $this->element->getValue(); + }; + return $this->executeCommand($commandCallback, "value could not be got"); + } + + /** + * Sets the given value on the wrapped element. + * + * If automatically waits for the wrapped element to be visible (up to the + * timeout set when finding it). + * + * @param string $value the value to set. + */ + public function setValue($value) { + $commandCallback = function() use ($value) { + $this->element->setValue($value); + }; + $this->executeCommandOnVisibleElement($commandCallback, "value could not be set"); + } + + /** + * Clicks on the wrapped element. + * + * If automatically waits for the wrapped element to be visible (up to the + * timeout set when finding it). + */ + public function click() { + $commandCallback = function() { + $this->element->click(); + }; + $this->executeCommandOnVisibleElement($commandCallback, "could not be clicked"); + } + + /** + * Executes the given command. + * + * If a StaleElementReference exception is thrown the wrapped element is + * found again and, then, the command is executed again. + * + * @param \Closure $commandCallback the command to execute. + * @param string $errorMessage an error message that describes the failed + * command (appended to the description of the element). + */ + private function executeCommand(\Closure $commandCallback, $errorMessage) { + if (!$this->handleFailedCommands) { + return $commandCallback(); + } + + try { + return $commandCallback(); + } catch (\WebDriver\Exception\StaleElementReference $exception) { + $this->printFailedCommandMessage($exception, $errorMessage); + } + + $this->element = $this->elementFinder->find(); + + return $commandCallback(); + } + + /** + * Executes the given command on a visible element. + * + * If a StaleElementReference exception is thrown the wrapped element is + * found again and, then, the command is executed again. If an + * ElementNotVisible exception is thrown it is waited for the wrapped + * element to be visible and, then, the command is executed again. + * + * @param \Closure $commandCallback the command to execute. + * @param string $errorMessage an error message that describes the failed + * command (appended to the description of the element). + */ + private function executeCommandOnVisibleElement(\Closure $commandCallback, $errorMessage) { + if (!$this->handleFailedCommands) { + return $commandCallback(); + } + + try { + return $this->executeCommand($commandCallback, $errorMessage); + } catch (\WebDriver\Exception\ElementNotVisible $exception) { + $this->printFailedCommandMessage($exception, $errorMessage); + } + + $this->waitForElementToBeVisible(); + + return $commandCallback(); + } + + /** + * Prints information about the failed command. + * + * @param \Exception exception the exception thrown by the command. + * @param string $errorMessage an error message that describes the failed + * command (appended to the description of the locator of the element). + */ + private function printFailedCommandMessage(\Exception $exception, $errorMessage) { + echo $this->elementFinder->getDescription() . " " . $errorMessage . "\n"; + echo "Exception message: " . $exception->getMessage() . "\n"; + echo "Trying again\n"; + } + + /** + * Waits for the wrapped element to be visible. + * + * This method waits up to the timeout used when finding the wrapped + * element; therefore, it may return when the element is still not visible. + * + * @return boolean true if the element is visible after the wait, false + * otherwise. + */ + private function waitForElementToBeVisible() { + $isVisibleCallback = function() { + return $this->isVisible(); + }; + $timeout = $this->elementFinder->getTimeout(); + $timeoutStep = $this->elementFinder->getTimeoutStep(); + + return Utils::waitFor($isVisibleCallback, $timeout, $timeoutStep); + } + +}