nextcloud/tests/acceptance/features/core/Actor.php

216 lines
7.4 KiB
PHP
Raw Normal View History

<?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/>.
*
*/
/**
* An actor in a test scenario.
*
* Every Actor object is intended to be used only in a single test scenario.
* An Actor can control its web browser thanks to the Mink Session received when
* it was created, so in each scenario each Actor must have its own Mink
* Session; the same Mink Session can be used by different Actors in different
* scenarios, but never by different Actors in the same scenario.
*
* The test servers used in an scenario can change between different test runs,
* so an Actor stores the base URL for the current test server being used; in
* most cases the tests are specified using relative paths that can be converted
* to the appropriate absolute URL using locatePath() in the step
* implementation.
*
* An Actor can find elements in its Mink Session using its find() method; it is
* a wrapper over the find() method provided by Mink that extends it with
* several features: the element can be looked for based on a Locator object, an
* 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.
*
Add automatic handling of common command failures of Mink elements Commands executed on Mink elements may fail for several reasons. ElementWrapper is introduced to automatically handle some of those situations, like StaleElementReference exceptions and ElementNotVisible exceptions. StaleElementReference exceptions are thrown when the command is executed on an element that is no longer attached to the DOM. When that happens the ElementWrapper finds again the element and executes the command again on the new element. ElementNotVisible exceptions are thrown when the command requires the element to be visible but the element is not. When that happens the ElementWrapper waits for the element to be visible before executing the command again. These changes are totally compatible with the current acceptance tests. They just make the tests more robust, but they do not change their behaviour. In fact, this should minimize some of the sporadic failures in the acceptance tests caused by their concurrent nature with respect to the web browser executing the commands. However, the ElementWrapper is not a silver bullet; it handles the most common situations, but it does not handle every possible scenario. For example, the acceptance tests would still fail sporadically if an element can become staled several times in a row (uncommon) or if it does not become visible before the timeout expires (which could still happen in a loaded system even if the components under test work right, but obviously it is not possible to wait indefinitely for them). Signed-off-by: Daniel Calviño Sánchez <danxuliu@gmail.com>
2017-05-05 23:54:20 +03:00
* 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
* before giving up without modifying the tests themselves. Note that the
* multiplier affects the timeout, but not the timeout step; the rate at which
* find() will try again to find the element does not change.
*
* All actors share a notebook in which data can be annotated. This makes
* possible to share data between different test steps, no matter which Actor
* performs them.
*/
class Actor {
/**
* @var string
*/
private $name;
/**
* @var \Behat\Mink\Session
*/
private $session;
/**
* @var string
*/
private $baseUrl;
/**
* @var float
*/
private $findTimeoutMultiplier;
/**
* @var array
*/
private $sharedNotebook;
/**
* Creates a new Actor.
*
* @param string $name the name of the actor.
* @param \Behat\Mink\Session $session the Mink Session used to control its
* web browser.
* @param string $baseUrl the base URL used when solving relative URLs.
* @param array $sharedNotebook the notebook shared between all actors.
*/
public function __construct($name, \Behat\Mink\Session $session, $baseUrl, &$sharedNotebook) {
$this->name = $name;
$this->session = $session;
$this->baseUrl = $baseUrl;
$this->sharedNotebook = &$sharedNotebook;
$this->findTimeoutMultiplier = 1;
}
/**
* Returns the name of this Actor.
*
* @return string the name of this Actor.
*/
public function getName() {
return $this->name;
}
/**
* Sets the base URL.
*
* @param string $baseUrl the base URL used when solving relative URLs.
*/
public function setBaseUrl($baseUrl) {
$this->baseUrl = $baseUrl;
}
/**
* Returns the multiplier for find timeouts.
*
* @return float the multiplier to apply to find timeouts.
*/
public function getFindTimeoutMultiplier() {
return $this->findTimeoutMultiplier;
}
/**
* Sets the multiplier for find timeouts.
*
* @param float $findTimeoutMultiplier the multiplier to apply to find
* timeouts.
*/
public function setFindTimeoutMultiplier($findTimeoutMultiplier) {
$this->findTimeoutMultiplier = $findTimeoutMultiplier;
}
/**
* Returns the Mink Session used to control its web browser.
*
* @return \Behat\Mink\Session the Mink Session used to control its web
* browser.
*/
public function getSession() {
return $this->session;
}
/**
* Returns the full path for the given relative path based on the base URL.
*
* @param string relativePath the relative path.
* @return string the full path.
*/
public function locatePath($relativePath) {
return $this->baseUrl . $relativePath;
}
/**
* Finds an element in the Mink Session of this Actor.
*
* The given element locator is relative to its ancestor (either another
* locator or an actual element); if it has no ancestor then the base
* document element is used.
*
* Sometimes an element may not be found simply because it has not appeared
* yet; for those cases this method supports trying again to find the
* element several times before giving up. The timeout parameter controls
* how much time to wait, at most, to find the element; the timeoutStep
* parameter controls how much time to wait before trying again to find the
* element. If ancestor locators need to be found the timeout is applied
* individually to each one, that is, if the timeout is 10 seconds the
* method will wait up to 10 seconds to find the ancestor of the ancestor
* and, then, up to 10 seconds to find the ancestor and, then, up to 10
* seconds to find the element. By default the timeout is 0, so the element
* and its ancestor will be looked for just once; the default time to wait
* before retrying is half a second. If the timeout is not 0 it will be
* affected by the multiplier set using setFindTimeoutMultiplier(), if any.
*
Add automatic handling of common command failures of Mink elements Commands executed on Mink elements may fail for several reasons. ElementWrapper is introduced to automatically handle some of those situations, like StaleElementReference exceptions and ElementNotVisible exceptions. StaleElementReference exceptions are thrown when the command is executed on an element that is no longer attached to the DOM. When that happens the ElementWrapper finds again the element and executes the command again on the new element. ElementNotVisible exceptions are thrown when the command requires the element to be visible but the element is not. When that happens the ElementWrapper waits for the element to be visible before executing the command again. These changes are totally compatible with the current acceptance tests. They just make the tests more robust, but they do not change their behaviour. In fact, this should minimize some of the sporadic failures in the acceptance tests caused by their concurrent nature with respect to the web browser executing the commands. However, the ElementWrapper is not a silver bullet; it handles the most common situations, but it does not handle every possible scenario. For example, the acceptance tests would still fail sporadically if an element can become staled several times in a row (uncommon) or if it does not become visible before the timeout expires (which could still happen in a loaded system even if the components under test work right, but obviously it is not possible to wait indefinitely for them). Signed-off-by: Daniel Calviño Sánchez <danxuliu@gmail.com>
2017-05-05 23:54:20 +03:00
* 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.
*
* @param Locator $elementLocator the locator for the element.
* @param float $timeout the number of seconds (decimals allowed) to wait at
* most for the element to appear.
* @param float $timeoutStep the number of seconds (decimals allowed) to
* wait before trying to find the element again.
Add automatic handling of common command failures of Mink elements Commands executed on Mink elements may fail for several reasons. ElementWrapper is introduced to automatically handle some of those situations, like StaleElementReference exceptions and ElementNotVisible exceptions. StaleElementReference exceptions are thrown when the command is executed on an element that is no longer attached to the DOM. When that happens the ElementWrapper finds again the element and executes the command again on the new element. ElementNotVisible exceptions are thrown when the command requires the element to be visible but the element is not. When that happens the ElementWrapper waits for the element to be visible before executing the command again. These changes are totally compatible with the current acceptance tests. They just make the tests more robust, but they do not change their behaviour. In fact, this should minimize some of the sporadic failures in the acceptance tests caused by their concurrent nature with respect to the web browser executing the commands. However, the ElementWrapper is not a silver bullet; it handles the most common situations, but it does not handle every possible scenario. For example, the acceptance tests would still fail sporadically if an element can become staled several times in a row (uncommon) or if it does not become visible before the timeout expires (which could still happen in a loaded system even if the components under test work right, but obviously it is not possible to wait indefinitely for them). Signed-off-by: Daniel Calviño Sánchez <danxuliu@gmail.com>
2017-05-05 23:54:20 +03:00
* @return ElementWrapper an ElementWrapper object for the element.
* @throws NoSuchElementException if the element, or its ancestor, can not
* be found.
*/
public function find(Locator $elementLocator, $timeout = 0, $timeoutStep = 0.5) {
$timeout = $timeout * $this->findTimeoutMultiplier;
$elementFinder = new ElementFinder($this->session, $elementLocator, $timeout, $timeoutStep);
Add automatic handling of common command failures of Mink elements Commands executed on Mink elements may fail for several reasons. ElementWrapper is introduced to automatically handle some of those situations, like StaleElementReference exceptions and ElementNotVisible exceptions. StaleElementReference exceptions are thrown when the command is executed on an element that is no longer attached to the DOM. When that happens the ElementWrapper finds again the element and executes the command again on the new element. ElementNotVisible exceptions are thrown when the command requires the element to be visible but the element is not. When that happens the ElementWrapper waits for the element to be visible before executing the command again. These changes are totally compatible with the current acceptance tests. They just make the tests more robust, but they do not change their behaviour. In fact, this should minimize some of the sporadic failures in the acceptance tests caused by their concurrent nature with respect to the web browser executing the commands. However, the ElementWrapper is not a silver bullet; it handles the most common situations, but it does not handle every possible scenario. For example, the acceptance tests would still fail sporadically if an element can become staled several times in a row (uncommon) or if it does not become visible before the timeout expires (which could still happen in a loaded system even if the components under test work right, but obviously it is not possible to wait indefinitely for them). Signed-off-by: Daniel Calviño Sánchez <danxuliu@gmail.com>
2017-05-05 23:54:20 +03:00
return new ElementWrapper($elementFinder);
}
/**
* Returns the shared notebook of the Actors.
*
* @return array the shared notebook of the Actors.
*/
public function &getSharedNotebook() {
return $this->sharedNotebook;
}
}