server/tests/acceptance/features/core/ElementWrapper.php

<?php

/**
 *
 * @copyright Copyright (c) 2017, Daniel Calviño Sánchez (danxuliu@gmail.com)
 *
 * @license GNU AGPL version 3 or any later version
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

/**
 * 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.
 *
 * MoveTargetOutOfBounds exceptions are sometimes thrown instead of
 * ElementNotVisible exceptions. This can happen when the Selenium2 driver for
 * Mink moves the cursor on an element using the "moveto" method of the
 * WebDriver session, for example, before clicking on an element. In that case,
 * if the element is not visible, "moveto" would throw a MoveTargetOutOfBounds
 * exception instead of an ElementNotVisible exception, so those cases are
 * handled like ElementNotVisible exceptions.
 *
 * 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). In a
 * similar way, MoveTargetOutOfBounds exceptions would be thrown again if
 * originally they were thrown because the element was visible but "out of
 * reach".
 *
 * 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 bool 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 or a MoveTargetOutOfBounds 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);
		} catch (\WebDriver\Exception\MoveTargetOutOfBounds $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);
	}

}