ElementFinder.php 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205
  1. <?php
  2. /**
  3. *
  4. * @copyright Copyright (c) 2017, Daniel Calviño Sánchez (danxuliu@gmail.com)
  5. *
  6. * @license GNU AGPL version 3 or any later version
  7. *
  8. * This program is free software: you can redistribute it and/or modify
  9. * it under the terms of the GNU Affero General Public License as
  10. * published by the Free Software Foundation, either version 3 of the
  11. * License, or (at your option) any later version.
  12. *
  13. * This program is distributed in the hope that it will be useful,
  14. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16. * GNU Affero General Public License for more details.
  17. *
  18. * You should have received a copy of the GNU Affero General Public License
  19. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  20. *
  21. */
  22. /**
  23. * Command object to find Mink elements.
  24. *
  25. * The element locator is relative to its ancestor (either another locator or an
  26. * actual element); if it has no ancestor then the base document element is
  27. * used.
  28. *
  29. * Sometimes an element may not be found simply because it has not appeared yet;
  30. * for those cases ElementFinder supports trying again to find the element
  31. * several times before giving up. The timeout parameter controls how much time
  32. * to wait, at most, to find the element; the timeoutStep parameter controls how
  33. * much time to wait before trying again to find the element. If ancestor
  34. * locators need to be found the timeout is applied individually to each one,
  35. * that is, if the timeout is 10 seconds the method will wait up to 10 seconds
  36. * to find the ancestor of the ancestor and, then, up to 10 seconds to find the
  37. * ancestor and, then, up to 10 seconds to find the element. By default the
  38. * timeout is 0, so the element and its ancestor will be looked for just once;
  39. * the default time to wait before retrying is half a second.
  40. *
  41. * In any case, if the element, or its ancestors, can not be found a
  42. * NoSuchElementException is thrown.
  43. */
  44. class ElementFinder {
  45. /**
  46. * Finds an element in the given Mink Session.
  47. *
  48. * @see ElementFinder
  49. */
  50. private static function findInternal(\Behat\Mink\Session $session, Locator $elementLocator, $timeout, $timeoutStep) {
  51. $element = null;
  52. $selector = $elementLocator->getSelector();
  53. $locator = $elementLocator->getLocator();
  54. $ancestorElement = self::findAncestorElement($session, $elementLocator, $timeout, $timeoutStep);
  55. $findCallback = function() use (&$element, $selector, $locator, $ancestorElement) {
  56. $element = $ancestorElement->find($selector, $locator);
  57. return $element !== null;
  58. };
  59. if (!Utils::waitFor($findCallback, $timeout, $timeoutStep)) {
  60. $message = $elementLocator->getDescription() . " could not be found";
  61. if ($timeout > 0) {
  62. $message = $message . " after $timeout seconds";
  63. }
  64. throw new NoSuchElementException($message);
  65. }
  66. return $element;
  67. }
  68. /**
  69. * Returns the ancestor element from which the given locator will be looked
  70. * for.
  71. *
  72. * If the ancestor of the given locator is another locator the element for
  73. * the ancestor locator is found and returned. If the ancestor of the given
  74. * locator is already an element that element is the one returned. If the
  75. * given locator has no ancestor then the base document element is returned.
  76. *
  77. * The timeout is used only when finding the element for the ancestor
  78. * locator; if the timeout expires a NoSuchElementException is thrown.
  79. *
  80. * @param \Behat\Mink\Session $session the Mink Session to get the ancestor
  81. * element from.
  82. * @param Locator $elementLocator the locator for the element to get its
  83. * ancestor.
  84. * @param float $timeout the number of seconds (decimals allowed) to wait at
  85. * most for the ancestor element to appear.
  86. * @param float $timeoutStep the number of seconds (decimals allowed) to
  87. * wait before trying to find the ancestor element again.
  88. * @return \Behat\Mink\Element\Element the ancestor element found.
  89. * @throws NoSuchElementException if the ancestor element can not be found.
  90. */
  91. private static function findAncestorElement(\Behat\Mink\Session $session, Locator $elementLocator, $timeout, $timeoutStep) {
  92. $ancestorElement = $elementLocator->getAncestor();
  93. if ($ancestorElement instanceof Locator) {
  94. try {
  95. $ancestorElement = self::findInternal($session, $ancestorElement, $timeout, $timeoutStep);
  96. } catch (NoSuchElementException $exception) {
  97. // Little hack to show the stack of ancestor elements that could
  98. // not be found, as Behat only shows the message of the last
  99. // exception in the chain.
  100. $message = $exception->getMessage() . "\n" .
  101. $elementLocator->getDescription() . " could not be found";
  102. if ($timeout > 0) {
  103. $message = $message . " after $timeout seconds";
  104. }
  105. throw new NoSuchElementException($message, $exception);
  106. }
  107. }
  108. if ($ancestorElement === null) {
  109. $ancestorElement = $session->getPage();
  110. }
  111. return $ancestorElement;
  112. }
  113. /**
  114. * @var \Behat\Mink\Session
  115. */
  116. private $session;
  117. /**
  118. * @param Locator
  119. */
  120. private $elementLocator;
  121. /**
  122. * @var float
  123. */
  124. private $timeout;
  125. /**
  126. * @var float
  127. */
  128. private $timeoutStep;
  129. /**
  130. * Creates a new ElementFinder.
  131. *
  132. * @param \Behat\Mink\Session $session the Mink Session to get the element
  133. * from.
  134. * @param Locator $elementLocator the locator for the element.
  135. * @param float $timeout the number of seconds (decimals allowed) to wait at
  136. * most for the element to appear.
  137. * @param float $timeoutStep the number of seconds (decimals allowed) to
  138. * wait before trying to find the element again.
  139. */
  140. public function __construct(\Behat\Mink\Session $session, Locator $elementLocator, $timeout, $timeoutStep) {
  141. $this->session = $session;
  142. $this->elementLocator = $elementLocator;
  143. $this->timeout = $timeout;
  144. $this->timeoutStep = $timeoutStep;
  145. }
  146. /**
  147. * Returns the description of the element to find.
  148. *
  149. * @return string the description of the element to find.
  150. */
  151. public function getDescription() {
  152. return $this->elementLocator->getDescription();
  153. }
  154. /**
  155. * Returns the timeout.
  156. *
  157. * @return float the number of seconds (decimals allowed) to wait at most
  158. * for the element to appear.
  159. */
  160. public function getTimeout() {
  161. return $this->timeout;
  162. }
  163. /**
  164. * Returns the timeout step.
  165. *
  166. * @return float the number of seconds (decimals allowed) to wait before
  167. * trying to find the element again.
  168. */
  169. public function getTimeoutStep() {
  170. return $this->timeoutStep;
  171. }
  172. /**
  173. * Finds an element using the parameters set in the constructor of this
  174. * ElementFinder.
  175. *
  176. * If the element, or its ancestors, can not be found a
  177. * NoSuchElementException is thrown.
  178. *
  179. * @return \Behat\Mink\Element\Element the element found.
  180. * @throws NoSuchElementException if the element, or its ancestor, can not
  181. * be found.
  182. */
  183. public function find() {
  184. return self::findInternal($this->session, $this->elementLocator, $this->timeout, $this->timeoutStep);
  185. }
  186. }