729ac1eff9bc0e7efc54dc1cefb548fa6f452da0
[moodle.git] / lib / behat / behat_base.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Base class of all steps definitions.
19  *
20  * This script is only called from Behat as part of it's integration
21  * in Moodle.
22  *
23  * @package   core
24  * @category  test
25  * @copyright 2012 David MonllaĆ³
26  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27  */
29 // NOTE: no MOODLE_INTERNAL test here, this file may be required by behat before including /config.php.
31 use Behat\Mink\Exception\DriverException;
32 use Behat\Mink\Exception\ExpectationException;
33 use Behat\Mink\Exception\ElementNotFoundException;
34 use Behat\Mink\Element\NodeElement;
35 use Behat\Mink\Element\Element;
36 use Behat\Mink\Session;
38 require_once(__DIR__ . '/classes/component_named_selector.php');
39 require_once(__DIR__ . '/classes/component_named_replacement.php');
41 /**
42  * Steps definitions base class.
43  *
44  * To extend by the steps definitions of the different Moodle components.
45  *
46  * It can not contain steps definitions to avoid duplicates, only utility
47  * methods shared between steps.
48  *
49  * @method NodeElement find_field(string $locator) Finds a form element
50  * @method NodeElement find_button(string $locator) Finds a form input submit element or a button
51  * @method NodeElement find_link(string $locator) Finds a link on a page
52  * @method NodeElement find_file(string $locator) Finds a forum input file element
53  *
54  * @package   core
55  * @category  test
56  * @copyright 2012 David MonllaĆ³
57  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
58  */
59 class behat_base extends Behat\MinkExtension\Context\RawMinkContext {
61     /**
62      * Small timeout.
63      *
64      * A reduced timeout for cases where self::TIMEOUT is too much
65      * and a simple $this->getSession()->getPage()->find() could not
66      * be enough.
67      *
68      * @deprecated since Moodle 3.7 MDL-64979 - please use get_reduced_timeout() instead
69      * @todo MDL-64982 This will be deleted in Moodle 4.1
70      * @see behat_base::get_reduced_timeout()
71      */
72     const REDUCED_TIMEOUT = 2;
74     /**
75      * The timeout for each Behat step (load page, wait for an element to load...).
76      *
77      * @deprecated since Moodle 3.7 MDL-64979 - please use get_timeout() instead
78      * @todo MDL-64982 This will be deleted in Moodle 4.1
79      * @see behat_base::get_timeout()
80      */
81     const TIMEOUT = 6;
83     /**
84      * And extended timeout for specific cases.
85      *
86      * @deprecated since Moodle 3.7 MDL-64979 - please use get_extended_timeout() instead
87      * @todo MDL-64982 This will be deleted in Moodle 4.1
88      * @see behat_base::get_extended_timeout()
89      */
90     const EXTENDED_TIMEOUT = 10;
92     /**
93      * The JS code to check that the page is ready.
94      */
95     const PAGE_READY_JS = '(typeof M !== "undefined" && M.util && M.util.pending_js && !Boolean(M.util.pending_js.length)) && (document.readyState === "complete")';
97     /**
98      * Locates url, based on provided path.
99      * Override to provide custom routing mechanism.
100      *
101      * @see Behat\MinkExtension\Context\MinkContext
102      * @param string $path
103      * @return string
104      */
105     protected function locate_path($path) {
106         $starturl = rtrim($this->getMinkParameter('base_url'), '/') . '/';
107         return 0 !== strpos($path, 'http') ? $starturl . ltrim($path, '/') : $path;
108     }
110     /**
111      * Returns the first matching element.
112      *
113      * @link http://mink.behat.org/#traverse-the-page-selectors
114      * @param string $selector The selector type (css, xpath, named...)
115      * @param mixed $locator It depends on the $selector, can be the xpath, a name, a css locator...
116      * @param Exception $exception Otherwise we throw exception with generic info
117      * @param NodeElement $node Spins around certain DOM node instead of the whole page
118      * @param int $timeout Forces a specific time out (in seconds).
119      * @return NodeElement
120      */
121     protected function find($selector, $locator, $exception = false, $node = false, $timeout = false) {
122         // Returns the first match.
123         $items = $this->find_all($selector, $locator, $exception, $node, $timeout);
124         return count($items) ? reset($items) : null;
125     }
127     /**
128      * Returns all matching elements.
129      *
130      * Adapter to Behat\Mink\Element\Element::findAll() using the spin() method.
131      *
132      * @link http://mink.behat.org/#traverse-the-page-selectors
133      * @param string $selector The selector type (css, xpath, named...)
134      * @param mixed $locator It depends on the $selector, can be the xpath, a name, a css locator...
135      * @param Exception $exception Otherwise we throw expcetion with generic info
136      * @param NodeElement $container Restrict the search to just children of the specified container
137      * @param int $timeout Forces a specific time out (in seconds). If 0 is provided the default timeout will be applied.
138      * @return array NodeElements list
139      */
140     protected function find_all($selector, $locator, $exception = false, $container = false, $timeout = false) {
141         // Throw exception, so dev knows it is not supported.
142         if ($selector === 'named') {
143             $exception = 'Using the "named" selector is deprecated as of 3.1. '
144                 .' Use the "named_partial" or use the "named_exact" selector instead.';
145             throw new ExpectationException($exception, $this->getSession());
146         }
148         // Generic info.
149         if (!$exception) {
150             // With named selectors we can be more specific.
151             if (($selector == 'named_exact') || ($selector == 'named_partial')) {
152                 $exceptiontype = $locator[0];
153                 $exceptionlocator = $locator[1];
155                 // If we are in a @javascript session all contents would be displayed as HTML characters.
156                 if ($this->running_javascript()) {
157                     $locator[1] = html_entity_decode($locator[1], ENT_NOQUOTES);
158                 }
160             } else {
161                 $exceptiontype = $selector;
162                 $exceptionlocator = $locator;
163             }
165             $exception = new ElementNotFoundException($this->getSession(), $exceptiontype, null, $exceptionlocator);
166         }
168         // How much we will be waiting for the element to appear.
169         if (!$timeout) {
170             $timeout = self::get_timeout();
171             $microsleep = false;
172         } else {
173             // Spinning each 0.1 seconds if the timeout was forced as we understand
174             // that is a special case and is good to refine the performance as much
175             // as possible.
176             $microsleep = true;
177         }
179         // Normalise the values in order to perform the search.
180         [
181             'selector' => $selector,
182             'locator' => $locator,
183             'container' => $container,
184         ] = $this->normalise_selector($selector, $locator, $container ?: $this->getSession()->getPage());
186         // Waits for the node to appear if it exists, otherwise will timeout and throw the provided exception.
187         return $this->spin(
188             function() use ($selector, $locator, $container) {
189                 return $container->findAll($selector, $locator);
190             }, [], $timeout, $exception, $microsleep
191         );
192     }
194     /**
195      * Normalise the locator and selector.
196      *
197      * @param string $selector The type of thing to search
198      * @param mixed $locator The locator value. Can be an array, but is more likely a string.
199      * @param Element $container An optional container to search within
200      * @return array The selector, locator, and container to search within
201      */
202     public function normalise_selector(string $selector, $locator, Element $container): array {
203         // Check for specific transformations for this selector type.
204         $transformfunction = "transform_find_for_{$selector}";
205         if (method_exists('behat_selectors', $transformfunction)) {
206             // A selector-specific transformation exists.
207             // Perform initial transformation of the selector within the current container.
208             [
209                 'selector' => $selector,
210                 'locator' => $locator,
211                 'container' => $container,
212             ] = behat_selectors::{$transformfunction}($this, $locator, $container);
213         }
215         // Normalise the css and xpath selector types.
216         if ('css_element' === $selector) {
217             $selector = 'css';
218         } else if ('xpath_element' === $selector) {
219             $selector = 'xpath';
220         }
222         // Convert to a named selector where the selector type is not a known selector.
223         $converttonamed = !$this->getSession()->getSelectorsHandler()->isSelectorRegistered($selector);
224         $converttonamed = $converttonamed && 'xpath' !== $selector;
225         if ($converttonamed) {
226             if (behat_partial_named_selector::is_deprecated_selector($selector)) {
227                 if ($replacement = behat_partial_named_selector::get_deprecated_replacement($selector)) {
228                     error_log("The '{$selector}' selector has been replaced with {$replacement}");
229                     $selector = $replacement;
230                 }
231             } else if (behat_exact_named_selector::is_deprecated_selector($selector)) {
232                 if ($replacement = behat_exact_named_selector::get_deprecated_replacement($selector)) {
233                     error_log("The '{$selector}' selector has been replaced with {$replacement}");
234                     $selector = $replacement;
235                 }
236             }
238             $allowedpartialselectors = behat_partial_named_selector::get_allowed_selectors();
239             $allowedexactselectors = behat_exact_named_selector::get_allowed_selectors();
240             if (isset($allowedpartialselectors[$selector])) {
241                 $locator = behat_selectors::normalise_named_selector($allowedpartialselectors[$selector], $locator);
242                 $selector = 'named_partial';
243             } else if (isset($allowedexactselectors[$selector])) {
244                 $locator = behat_selectors::normalise_named_selector($allowedexactselectors[$selector], $locator);
245                 $selector = 'named_exact';
246             } else {
247                 throw new ExpectationException("The '{$selector}' selector type is not registered.", $this->getSession()->getDriver());
248             }
249         }
251         return [
252             'selector' => $selector,
253             'locator' => $locator,
254             'container' => $container,
255         ];
256     }
258     /**
259      * Finds DOM nodes in the page using named selectors.
260      *
261      * The point of using this method instead of Mink ones is the spin
262      * method of behat_base::find() that looks for the element until it
263      * is available or it timeouts, this avoids the false failures received
264      * when selenium tries to execute commands on elements that are not
265      * ready to be used.
266      *
267      * All steps that requires elements to be available before interact with
268      * them should use one of the find* methods.
269      *
270      * The methods calls requires a {'find_' . $elementtype}($locator)
271      * format, like find_link($locator), find_select($locator),
272      * find_button($locator)...
273      *
274      * @link http://mink.behat.org/#named-selectors
275      * @throws coding_exception
276      * @param string $name The name of the called method
277      * @param mixed $arguments
278      * @return NodeElement
279      */
280     public function __call($name, $arguments) {
281         if (substr($name, 0, 5) === 'find_') {
282             return call_user_func_array([$this, 'find'], array_merge(
283                 [substr($name, 5)],
284                 $arguments
285             ));
286         }
288         throw new coding_exception("The '{$name}' method does not exist");
289     }
291     /**
292      * Escapes the double quote character.
293      *
294      * Double quote is the argument delimiter, it can be escaped
295      * with a backslash, but we auto-remove this backslashes
296      * before the step execution, this method is useful when using
297      * arguments as arguments for other steps.
298      *
299      * @param string $string
300      * @return string
301      */
302     public function escape($string) {
303         return str_replace('"', '\"', $string);
304     }
306     /**
307      * Executes the passed closure until returns true or time outs.
308      *
309      * In most cases the document.readyState === 'complete' will be enough, but sometimes JS
310      * requires more time to be completely loaded or an element to be visible or whatever is required to
311      * perform some action on an element; this method receives a closure which should contain the
312      * required statements to ensure the step definition actions and assertions have all their needs
313      * satisfied and executes it until they are satisfied or it timeouts. Redirects the return of the
314      * closure to the caller.
315      *
316      * The closures requirements to work well with this spin method are:
317      * - Must return false, null or '' if something goes wrong
318      * - Must return something != false if finishes as expected, this will be the (mixed) value
319      * returned by spin()
320      *
321      * The arguments of the closure are mixed, use $args depending on your needs.
322      *
323      * You can provide an exception to give more accurate feedback to tests writers, otherwise the
324      * closure exception will be used, but you must provide an exception if the closure does not throw
325      * an exception.
326      *
327      * @throws Exception If it timeouts without receiving something != false from the closure
328      * @param Function|array|string $lambda The function to execute or an array passed to call_user_func (maps to a class method)
329      * @param mixed $args Arguments to pass to the closure
330      * @param int $timeout Timeout in seconds
331      * @param Exception $exception The exception to throw in case it time outs.
332      * @param bool $microsleep If set to true it'll sleep micro seconds rather than seconds.
333      * @return mixed The value returned by the closure
334      */
335     protected function spin($lambda, $args = false, $timeout = false, $exception = false, $microsleep = false) {
337         // Using default timeout which is pretty high.
338         if (!$timeout) {
339             $timeout = self::get_timeout();
340         }
342         $start = microtime(true);
343         $end = $start + $timeout;
345         do {
346             // We catch the exception thrown by the step definition to execute it again.
347             try {
348                 // We don't check with !== because most of the time closures will return
349                 // direct Behat methods returns and we are not sure it will be always (bool)false
350                 // if it just runs the behat method without returning anything $return == null.
351                 if ($return = call_user_func($lambda, $this, $args)) {
352                     return $return;
353                 }
354             } catch (Exception $e) {
355                 // We would use the first closure exception if no exception has been provided.
356                 if (!$exception) {
357                     $exception = $e;
358                 }
359             }
361             if (!$this->running_javascript()) {
362                 break;
363             }
365             usleep(100000);
367         } while (microtime(true) < $end);
369         // Using coding_exception as is a development issue if no exception has been provided.
370         if (!$exception) {
371             $exception = new coding_exception('spin method requires an exception if the callback does not throw an exception');
372         }
374         // Throwing exception to the user.
375         throw $exception;
376     }
378     /**
379      * Gets a NodeElement based on the locator and selector type received as argument from steps definitions.
380      *
381      * Use behat_base::get_text_selector_node() for text-based selectors.
382      *
383      * @throws ElementNotFoundException Thrown by behat_base::find
384      * @param string $selectortype
385      * @param string $element
386      * @return NodeElement
387      */
388     protected function get_selected_node($selectortype, $element) {
389         return $this->find($selectortype, $element);
390     }
392     /**
393      * Gets a NodeElement based on the locator and selector type received as argument from steps definitions.
394      *
395      * @throws ElementNotFoundException Thrown by behat_base::find
396      * @param string $selectortype
397      * @param string $element
398      * @return NodeElement
399      */
400     protected function get_text_selector_node($selectortype, $element) {
401         // Getting Mink selector and locator.
402         list($selector, $locator) = $this->transform_text_selector($selectortype, $element);
404         // Returns the NodeElement.
405         return $this->find($selector, $locator);
406     }
408     /**
409      * Gets the requested element inside the specified container.
410      *
411      * @throws ElementNotFoundException Thrown by behat_base::find
412      * @param mixed $selectortype The element selector type.
413      * @param mixed $element The element locator.
414      * @param mixed $containerselectortype The container selector type.
415      * @param mixed $containerelement The container locator.
416      * @return NodeElement
417      */
418     protected function get_node_in_container($selectortype, $element, $containerselectortype, $containerelement) {
419         // Gets the container, it will always be text based.
420         $containernode = $this->get_text_selector_node($containerselectortype, $containerelement);
422         $locatorexceptionmsg = $element . '" in the "' . $containerelement. '" "' . $containerselectortype. '"';
423         $exception = new ElementNotFoundException($this->getSession(), $selectortype, null, $locatorexceptionmsg);
425         return $this->find($selectortype, $element, $exception, $containernode);
426     }
428     /**
429      * Transforms from step definition's argument style to Mink format.
430      *
431      * Mink has 3 different selectors css, xpath and named, where named
432      * selectors includes link, button, field... to simplify and group multiple
433      * steps in one we use the same interface, considering all link, buttons...
434      * at the same level as css selectors and xpath; this method makes the
435      * conversion from the arguments received by the steps to the selectors and locators
436      * required to interact with Mink.
437      *
438      * @throws ExpectationException
439      * @param string $selectortype It can be css, xpath or any of the named selectors.
440      * @param string $element The locator (or string) we are looking for.
441      * @return array Contains the selector and the locator expected by Mink.
442      */
443     protected function transform_selector($selectortype, $element) {
444         // Here we don't know if an allowed text selector is being used.
445         $selectors = behat_selectors::get_allowed_selectors();
446         if (!isset($selectors[$selectortype])) {
447             throw new ExpectationException('The "' . $selectortype . '" selector type does not exist', $this->getSession());
448         }
450         [
451             'selector' => $selector,
452             'locator' => $locator,
453         ] = $this->normalise_selector($selectortype, $element, $this->getSession()->getPage());
455         return [$selector, $locator];
456     }
458     /**
459      * Transforms from step definition's argument style to Mink format.
460      *
461      * Delegates all the process to behat_base::transform_selector() checking
462      * the provided $selectortype.
463      *
464      * @throws ExpectationException
465      * @param string $selectortype It can be css, xpath or any of the named selectors.
466      * @param string $element The locator (or string) we are looking for.
467      * @return array Contains the selector and the locator expected by Mink.
468      */
469     protected function transform_text_selector($selectortype, $element) {
471         $selectors = behat_selectors::get_allowed_text_selectors();
472         if (empty($selectors[$selectortype])) {
473             throw new ExpectationException('The "' . $selectortype . '" selector can not be used to select text nodes', $this->getSession());
474         }
476         return $this->transform_selector($selectortype, $element);
477     }
479     /**
480      * Returns whether the scenario is running in a browser that can run Javascript or not.
481      *
482      * @return boolean
483      */
484     protected function running_javascript() {
485         return get_class($this->getSession()->getDriver()) !== 'Behat\Mink\Driver\GoutteDriver';
486     }
488     /**
489      * Checks if the current page is part of the mobile app.
490      *
491      * @return bool True if it's in the app
492      */
493     protected function is_in_app() : bool {
494         // Cannot be in the app if there's no @app tag on scenario.
495         if (!$this->has_tag('app')) {
496             return false;
497         }
499         // Check on page to see if it's an app page. Safest way is to look for added JavaScript.
500         return $this->getSession()->evaluateScript('typeof window.behat') === 'object';
501     }
503     /**
504      * Spins around an element until it exists
505      *
506      * @throws ExpectationException
507      * @param string $locator
508      * @param string $selectortype
509      * @return void
510      */
511     protected function ensure_element_exists($locator, $selectortype) {
512         // Exception if it timesout and the element is still there.
513         $msg = "The '{$locator}' element does not exist and should";
514         $exception = new ExpectationException($msg, $this->getSession());
516         // Normalise the values in order to perform the search.
517         [
518             'selector' => $selector,
519             'locator' => $locator,
520             'container' => $container,
521         ] = $this->normalise_selector($selectortype, $locator, $this->getSession()->getPage());
523         // It will stop spinning once the find() method returns true.
524         $this->spin(
525             function() use ($selector, $locator, $container) {
526                 if ($container->find($selector, $locator)) {
527                     return true;
528                 }
529                 return false;
530             },
531             [],
532             self::get_extended_timeout(),
533             $exception,
534             true
535         );
536     }
538     /**
539      * Spins until the element does not exist
540      *
541      * @throws ExpectationException
542      * @param string $locator
543      * @param string $selectortype
544      * @return void
545      */
546     protected function ensure_element_does_not_exist($locator, $selectortype) {
547         // Exception if it timesout and the element is still there.
548         $msg = "The '{$locator}' element exists and should not exist";
549         $exception = new ExpectationException($msg, $this->getSession());
551         // Normalise the values in order to perform the search.
552         [
553             'selector' => $selector,
554             'locator' => $locator,
555             'container' => $container,
556         ] = $this->normalise_selector($selectortype, $locator, $this->getSession()->getPage());
558         // It will stop spinning once the find() method returns false.
559         $this->spin(
560             function() use ($selector, $locator, $container) {
561                 if ($container->find($selector, $locator)) {
562                     return false;
563                 }
564                 return true;
565             },
566             // Note: We cannot use $this because the find will then be $this->find(), which leads us to a nested spin().
567             // We cannot nest spins because the outer spin times out before the inner spin completes.
568             [],
569             self::get_extended_timeout(),
570             $exception,
571             true
572         );
573     }
575     /**
576      * Ensures that the provided node is visible and we can interact with it.
577      *
578      * @throws ExpectationException
579      * @param NodeElement $node
580      * @return void Throws an exception if it times out without the element being visible
581      */
582     protected function ensure_node_is_visible($node) {
584         if (!$this->running_javascript()) {
585             return;
586         }
588         // Exception if it timesout and the element is still there.
589         $msg = 'The "' . $node->getXPath() . '" xpath node is not visible and it should be visible';
590         $exception = new ExpectationException($msg, $this->getSession());
592         // It will stop spinning once the isVisible() method returns true.
593         $this->spin(
594             function($context, $args) {
595                 if ($args->isVisible()) {
596                     return true;
597                 }
598                 return false;
599             },
600             $node,
601             self::get_extended_timeout(),
602             $exception,
603             true
604         );
605     }
607     /**
608      * Ensures that the provided node has a attribute value set. This step can be used to check if specific
609      * JS has finished modifying the node.
610      *
611      * @throws ExpectationException
612      * @param NodeElement $node
613      * @param string $attribute attribute name
614      * @param string $attributevalue attribute value to check.
615      * @return void Throws an exception if it times out without the element being visible
616      */
617     protected function ensure_node_attribute_is_set($node, $attribute, $attributevalue) {
619         if (!$this->running_javascript()) {
620             return;
621         }
623         // Exception if it timesout and the element is still there.
624         $msg = 'The "' . $node->getXPath() . '" xpath node is not visible and it should be visible';
625         $exception = new ExpectationException($msg, $this->getSession());
627         // It will stop spinning once the $args[1]) == $args[2], and method returns true.
628         $this->spin(
629             function($context, $args) {
630                 if ($args[0]->getAttribute($args[1]) == $args[2]) {
631                     return true;
632                 }
633                 return false;
634             },
635             array($node, $attribute, $attributevalue),
636             self::get_extended_timeout(),
637             $exception,
638             true
639         );
640     }
642     /**
643      * Ensures that the provided element is visible and we can interact with it.
644      *
645      * Returns the node in case other actions are interested in using it.
646      *
647      * @throws ExpectationException
648      * @param string $element
649      * @param string $selectortype
650      * @return NodeElement Throws an exception if it times out without being visible
651      */
652     protected function ensure_element_is_visible($element, $selectortype) {
654         if (!$this->running_javascript()) {
655             return;
656         }
658         $node = $this->get_selected_node($selectortype, $element);
659         $this->ensure_node_is_visible($node);
661         return $node;
662     }
664     /**
665      * Ensures that all the page's editors are loaded.
666      *
667      * @deprecated since Moodle 2.7 MDL-44084 - please do not use this function any more.
668      * @throws ElementNotFoundException
669      * @throws ExpectationException
670      * @return void
671      */
672     protected function ensure_editors_are_loaded() {
673         global $CFG;
675         if (empty($CFG->behat_usedeprecated)) {
676             debugging('Function behat_base::ensure_editors_are_loaded() is deprecated. It is no longer required.');
677         }
678         return;
679     }
681     /**
682      * Checks if the current scenario, or its feature, has a specified tag.
683      *
684      * @param string $tag Tag to check
685      * @return bool True if the tag exists in scenario or feature
686      */
687     public function has_tag(string $tag) : bool {
688         return array_key_exists($tag, behat_hooks::get_tags_for_scenario());
689     }
691     /**
692      * Change browser window size.
693      *   - small: 640x480
694      *   - medium: 1024x768
695      *   - large: 2560x1600
696      *
697      * @param string $windowsize size of window.
698      * @param bool $viewport If true, changes viewport rather than window size
699      * @throws ExpectationException
700      */
701     protected function resize_window($windowsize, $viewport = false) {
702         // Non JS don't support resize window.
703         if (!$this->running_javascript()) {
704             return;
705         }
707         switch ($windowsize) {
708             case "small":
709                 $width = 1024;
710                 $height = 768;
711                 break;
712             case "medium":
713                 $width = 1366;
714                 $height = 768;
715                 break;
716             case "large":
717                 $width = 2560;
718                 $height = 1600;
719                 break;
720             default:
721                 preg_match('/^(\d+x\d+)$/', $windowsize, $matches);
722                 if (empty($matches) || (count($matches) != 2)) {
723                     throw new ExpectationException("Invalid screen size, can't resize", $this->getSession());
724                 }
725                 $size = explode('x', $windowsize);
726                 $width = (int) $size[0];
727                 $height = (int) $size[1];
728         }
729         if ($viewport) {
730             // When setting viewport size, we set it so that the document width will be exactly
731             // as specified, assuming that there is a vertical scrollbar. (In cases where there is
732             // no scrollbar it will be slightly wider. We presume this is rare and predictable.)
733             // The window inner height will be as specified, which means the available viewport will
734             // actually be smaller if there is a horizontal scrollbar. We assume that horizontal
735             // scrollbars are rare so this doesn't matter.
736             $offset = $this->getSession()->getDriver()->evaluateScript(
737                     'return (function() { var before = document.body.style.overflowY;' .
738                     'document.body.style.overflowY = "scroll";' .
739                     'var result = {};' .
740                     'result.x = window.outerWidth - document.body.offsetWidth;' .
741                     'result.y = window.outerHeight - window.innerHeight;' .
742                     'document.body.style.overflowY = before;' .
743                     'return result; })();');
744             $width += $offset['x'];
745             $height += $offset['y'];
746         }
748         $this->getSession()->getDriver()->resizeWindow($width, $height);
749     }
751     /**
752      * Waits for all the JS to be loaded.
753      *
754      * @return  bool Whether any JS is still pending completion.
755      */
756     public function wait_for_pending_js() {
757         if (!$this->running_javascript()) {
758             // JS is not available therefore there is nothing to wait for.
759             return false;
760         }
762         return static::wait_for_pending_js_in_session($this->getSession());
763     }
765     /**
766      * Waits for all the JS to be loaded.
767      *
768      * @param   Session $session The Mink Session where JS can be run
769      * @return  bool Whether any JS is still pending completion.
770      */
771     public static function wait_for_pending_js_in_session(Session $session) {
772         // We don't use behat_base::spin() here as we don't want to end up with an exception
773         // if the page & JSs don't finish loading properly.
774         for ($i = 0; $i < self::get_extended_timeout() * 10; $i++) {
775             $pending = '';
776             try {
777                 $jscode = trim(preg_replace('/\s+/', ' ', '
778                     return (function() {
779                         if (typeof M === "undefined") {
780                             if (document.readyState === "complete") {
781                                 return "";
782                             } else {
783                                 return "incomplete";
784                             }
785                         } else if (' . self::PAGE_READY_JS . ') {
786                             return "";
787                         } else if (typeof M.util !== "undefined") {
788                             return M.util.pending_js.join(":");
789                         } else {
790                             return "incomplete"
791                         }
792                     }());'));
793                 $pending = $session->evaluateScript($jscode);
794             } catch (NoSuchWindow $nsw) {
795                 // We catch an exception here, in case we just closed the window we were interacting with.
796                 // No javascript is running if there is no window right?
797                 $pending = '';
798             } catch (UnknownError $e) {
799                 // M is not defined when the window or the frame don't exist anymore.
800                 if (strstr($e->getMessage(), 'M is not defined') != false) {
801                     $pending = '';
802                 }
803             }
805             // If there are no pending JS we stop waiting.
806             if ($pending === '') {
807                 return true;
808             }
810             // 0.1 seconds.
811             usleep(100000);
812         }
814         // Timeout waiting for JS to complete. It will be caught and forwarded to behat_hooks::i_look_for_exceptions().
815         // It is unlikely that Javascript code of a page or an AJAX request needs more than get_extended_timeout() seconds
816         // to be loaded, although when pages contains Javascript errors M.util.js_complete() can not be executed, so the
817         // number of JS pending code and JS completed code will not match and we will reach this point.
818         throw new \Exception('Javascript code and/or AJAX requests are not ready after ' .
819                 self::get_extended_timeout() .
820                 ' seconds. There is a Javascript error or the code is extremely slow (' . $pending .
821                 '). If you are using a slow machine, consider setting $CFG->behat_increasetimeout.');
822     }
824     /**
825      * Internal step definition to find exceptions, debugging() messages and PHP debug messages.
826      *
827      * Part of behat_hooks class as is part of the testing framework, is auto-executed
828      * after each step so no features will splicitly use it.
829      *
830      * @throws Exception Unknown type, depending on what we caught in the hook or basic \Exception.
831      * @see Moodle\BehatExtension\Tester\MoodleStepTester
832      */
833     public function look_for_exceptions() {
834         // Wrap in try in case we were interacting with a closed window.
835         try {
837             // Exceptions.
838             $exceptionsxpath = "//div[@data-rel='fatalerror']";
839             // Debugging messages.
840             $debuggingxpath = "//div[@data-rel='debugging']";
841             // PHP debug messages.
842             $phperrorxpath = "//div[@data-rel='phpdebugmessage']";
843             // Any other backtrace.
844             $othersxpath = "(//*[contains(., ': call to ')])[1]";
846             $xpaths = array($exceptionsxpath, $debuggingxpath, $phperrorxpath, $othersxpath);
847             $joinedxpath = implode(' | ', $xpaths);
849             // Joined xpath expression. Most of the time there will be no exceptions, so this pre-check
850             // is faster than to send the 4 xpath queries for each step.
851             if (!$this->getSession()->getDriver()->find($joinedxpath)) {
852                 // Check if we have recorded any errors in driver process.
853                 $phperrors = behat_get_shutdown_process_errors();
854                 if (!empty($phperrors)) {
855                     foreach ($phperrors as $error) {
856                         $errnostring = behat_get_error_string($error['type']);
857                         $msgs[] = $errnostring . ": " .$error['message'] . " at " . $error['file'] . ": " . $error['line'];
858                     }
859                     $msg = "PHP errors found:\n" . implode("\n", $msgs);
860                     throw new \Exception(htmlentities($msg));
861                 }
863                 return;
864             }
866             // Exceptions.
867             if ($errormsg = $this->getSession()->getPage()->find('xpath', $exceptionsxpath)) {
869                 // Getting the debugging info and the backtrace.
870                 $errorinfoboxes = $this->getSession()->getPage()->findAll('css', 'div.alert-error');
871                 // If errorinfoboxes is empty, try find alert-danger (bootstrap4) class.
872                 if (empty($errorinfoboxes)) {
873                     $errorinfoboxes = $this->getSession()->getPage()->findAll('css', 'div.alert-danger');
874                 }
875                 // If errorinfoboxes is empty, try find notifytiny (original) class.
876                 if (empty($errorinfoboxes)) {
877                     $errorinfoboxes = $this->getSession()->getPage()->findAll('css', 'div.notifytiny');
878                 }
880                 // If errorinfoboxes is empty, try find ajax/JS exception in dialogue.
881                 if (empty($errorinfoboxes)) {
882                     $errorinfoboxes = $this->getSession()->getPage()->findAll('css', 'div.moodle-exception-message');
884                     // If ajax/JS exception.
885                     if ($errorinfoboxes) {
886                         $errorinfo = $this->get_debug_text($errorinfoboxes[0]->getHtml());
887                     }
889                 } else {
890                     $errorinfo = $this->get_debug_text($errorinfoboxes[0]->getHtml()) . "\n" .
891                         $this->get_debug_text($errorinfoboxes[1]->getHtml());
892                 }
894                 $msg = "Moodle exception: " . $errormsg->getText() . "\n" . $errorinfo;
895                 throw new \Exception(html_entity_decode($msg));
896             }
898             // Debugging messages.
899             if ($debuggingmessages = $this->getSession()->getPage()->findAll('xpath', $debuggingxpath)) {
900                 $msgs = array();
901                 foreach ($debuggingmessages as $debuggingmessage) {
902                     $msgs[] = $this->get_debug_text($debuggingmessage->getHtml());
903                 }
904                 $msg = "debugging() message/s found:\n" . implode("\n", $msgs);
905                 throw new \Exception(html_entity_decode($msg));
906             }
908             // PHP debug messages.
909             if ($phpmessages = $this->getSession()->getPage()->findAll('xpath', $phperrorxpath)) {
911                 $msgs = array();
912                 foreach ($phpmessages as $phpmessage) {
913                     $msgs[] = $this->get_debug_text($phpmessage->getHtml());
914                 }
915                 $msg = "PHP debug message/s found:\n" . implode("\n", $msgs);
916                 throw new \Exception(html_entity_decode($msg));
917             }
919             // Any other backtrace.
920             // First looking through xpath as it is faster than get and parse the whole page contents,
921             // we get the contents and look for matches once we found something to suspect that there is a backtrace.
922             if ($this->getSession()->getDriver()->find($othersxpath)) {
923                 $backtracespattern = '/(line [0-9]* of [^:]*: call to [\->&;:a-zA-Z_\x7f-\xff][\->&;:a-zA-Z0-9_\x7f-\xff]*)/';
924                 if (preg_match_all($backtracespattern, $this->getSession()->getPage()->getContent(), $backtraces)) {
925                     $msgs = array();
926                     foreach ($backtraces[0] as $backtrace) {
927                         $msgs[] = $backtrace . '()';
928                     }
929                     $msg = "Other backtraces found:\n" . implode("\n", $msgs);
930                     throw new \Exception(htmlentities($msg));
931                 }
932             }
934         } catch (NoSuchWindow $e) {
935             // If we were interacting with a popup window it will not exists after closing it.
936         } catch (DriverException $e) {
937             // Same reason as above.
938         }
939     }
941     /**
942      * Converts HTML tags to line breaks to display the info in CLI
943      *
944      * @param string $html
945      * @return string
946      */
947     protected function get_debug_text($html) {
949         // Replacing HTML tags for new lines and keeping only the text.
950         $notags = preg_replace('/<+\s*\/*\s*([A-Z][A-Z0-9]*)\b[^>]*\/*\s*>*/i', "\n", $html);
951         return preg_replace("/(\n)+/s", "\n", $notags);
952     }
954     /**
955      * Helper function to execute api in a given context.
956      *
957      * @param string $contextapi context in which api is defined.
958      * @param array $params list of params to pass.
959      * @throws Exception
960      */
961     protected function execute($contextapi, $params = array()) {
962         if (!is_array($params)) {
963             $params = array($params);
964         }
966         // Get required context and execute the api.
967         $contextapi = explode("::", $contextapi);
968         $context = behat_context_helper::get($contextapi[0]);
969         call_user_func_array(array($context, $contextapi[1]), $params);
971         // NOTE: Wait for pending js and look for exception are not optional, as this might lead to unexpected results.
972         // Don't make them optional for performance reasons.
974         // Wait for pending js.
975         $this->wait_for_pending_js();
977         // Look for exceptions.
978         $this->look_for_exceptions();
979     }
981     /**
982      * Get the actual user in the behat session (note $USER does not correspond to the behat session's user).
983      * @return mixed
984      * @throws coding_exception
985      */
986     protected function get_session_user() {
987         global $DB;
989         $sid = $this->getSession()->getCookie('MoodleSession');
990         if (empty($sid)) {
991             throw new coding_exception('failed to get moodle session');
992         }
993         $userid = $DB->get_field('sessions', 'userid', ['sid' => $sid]);
994         if (empty($userid)) {
995             throw new coding_exception('failed to get user from seession id '.$sid);
996         }
997         return $DB->get_record('user', ['id' => $userid]);
998     }
1000     /**
1001      * Set current $USER, reset access cache.
1002      *
1003      * In some cases, behat will execute the code as admin but in many cases we need to set an specific user as some
1004      * API's might rely on the logged user to take some action.
1005      *
1006      * @param null|int|stdClass $user user record, null or 0 means non-logged-in, positive integer means userid
1007      */
1008     public static function set_user($user = null) {
1009         global $DB;
1011         if (is_object($user)) {
1012             $user = clone($user);
1013         } else if (!$user) {
1014             // Assign valid data to admin user (some generator-related code needs a valid user).
1015             $user = $DB->get_record('user', array('username' => 'admin'));
1016         } else {
1017             $user = $DB->get_record('user', array('id' => $user));
1018         }
1019         unset($user->description);
1020         unset($user->access);
1021         unset($user->preference);
1023         // Ensure session is empty, as it may contain caches and user specific info.
1024         \core\session\manager::init_empty_session();
1026         \core\session\manager::set_user($user);
1027     }
1028     /**
1029      * Trigger click on node via javascript instead of actually clicking on it via pointer.
1030      *
1031      * This function resolves the issue of nested elements with click listeners or links - in these cases clicking via
1032      * the pointer may accidentally cause a click on the wrong element.
1033      * Example of issue: clicking to expand navigation nodes when the config value linkadmincategories is enabled.
1034      * @param NodeElement $node
1035      */
1036     protected function js_trigger_click($node) {
1037         if (!$this->running_javascript()) {
1038             $node->click();
1039         }
1040         $this->ensure_node_is_visible($node); // Ensures hidden elements can't be clicked.
1041         $xpath = $node->getXpath();
1042         $driver = $this->getSession()->getDriver();
1043         if ($driver instanceof \Moodle\BehatExtension\Driver\MoodleSelenium2Driver) {
1044             $script = "Syn.click({{ELEMENT}})";
1045             $driver->triggerSynScript($xpath, $script);
1046         } else {
1047             $driver->click($xpath);
1048         }
1049     }
1051     /**
1052      * Convert page names to URLs for steps like 'When I am on the "[page name]" page'.
1053      *
1054      * You should override this as appropriate for your plugin. The method
1055      * {@link behat_navigation::resolve_core_page_url()} is a good example.
1056      *
1057      * Your overridden method should document the recognised page types with
1058      * a table like this:
1059      *
1060      * Recognised page names are:
1061      * | Page            | Description                                                    |
1062      *
1063      * @param string $page name of the page, with the component name removed e.g. 'Admin notification'.
1064      * @return moodle_url the corresponding URL.
1065      * @throws Exception with a meaningful error message if the specified page cannot be found.
1066      */
1067     protected function resolve_page_url(string $page): moodle_url {
1068         throw new Exception('Component "' . get_class($this) .
1069                 '" does not support the generic \'When I am on the "' . $page .
1070                 '" page\' navigation step.');
1071     }
1073     /**
1074      * Convert page names to URLs for steps like 'When I am on the "[identifier]" "[page type]" page'.
1075      *
1076      * A typical example might be:
1077      *     When I am on the "Test quiz" "mod_quiz > Responses report" page
1078      * which would cause this method in behat_mod_quiz to be called with
1079      * arguments 'Responses report', 'Test quiz'.
1080      *
1081      * You should override this as appropriate for your plugin. The method
1082      * {@link behat_navigation::resolve_core_page_instance_url()} is a good example.
1083      *
1084      * Your overridden method should document the recognised page types with
1085      * a table like this:
1086      *
1087      * Recognised page names are:
1088      * | Type      | identifier meaning | Description                                     |
1089      *
1090      * @param string $type identifies which type of page this is, e.g. 'Attempt review'.
1091      * @param string $identifier identifies the particular page, e.g. 'Test quiz > student > Attempt 1'.
1092      * @return moodle_url the corresponding URL.
1093      * @throws Exception with a meaningful error message if the specified page cannot be found.
1094      */
1095     protected function resolve_page_instance_url(string $type, string $identifier): moodle_url {
1096         throw new Exception('Component "' . get_class($this) .
1097                 '" does not support the generic \'When I am on the "' . $identifier .
1098                 '" "' . $type . '" page\' navigation step.');
1099     }
1101     /**
1102      * Gets the required timeout in seconds.
1103      *
1104      * @param int $timeout One of the TIMEOUT constants
1105      * @return int Actual timeout (in seconds)
1106      */
1107     protected static function get_real_timeout(int $timeout) : int {
1108         global $CFG;
1109         if (!empty($CFG->behat_increasetimeout)) {
1110             return $timeout * $CFG->behat_increasetimeout;
1111         } else {
1112             return $timeout;
1113         }
1114     }
1116     /**
1117      * Gets the default timeout.
1118      *
1119      * The timeout for each Behat step (load page, wait for an element to load...).
1120      *
1121      * @return int Timeout in seconds
1122      */
1123     public static function get_timeout() : int {
1124         return self::get_real_timeout(6);
1125     }
1127     /**
1128      * Gets the reduced timeout.
1129      *
1130      * A reduced timeout for cases where self::get_timeout() is too much
1131      * and a simple $this->getSession()->getPage()->find() could not
1132      * be enough.
1133      *
1134      * @return int Timeout in seconds
1135      */
1136     public static function get_reduced_timeout() : int {
1137         return self::get_real_timeout(2);
1138     }
1140     /**
1141      * Gets the extended timeout.
1142      *
1143      * A longer timeout for cases where the normal timeout is not enough.
1144      *
1145      * @return int Timeout in seconds
1146      */
1147     public static function get_extended_timeout() : int {
1148         return self::get_real_timeout(10);
1149     }
1151     /**
1152      * Return a list of the exact named selectors for the component.
1153      *
1154      * Named selectors are what make Behat steps like
1155      *   Then I should see "Useful text" in the "General" "fieldset"
1156      * work. Here, "fieldset" is the named selector, and "General" is the locator.
1157      *
1158      * If you override this method in your plugin (e.g. mod_mymod), to define
1159      * new selectors specific to your plugin. For example, if you returned
1160      *   new behat_component_named_selector('Thingy',
1161      *           [".//some/xpath//img[contains(@alt, %locator%)]/.."])
1162      * then
1163      *   Then I should see "Useful text" in the "Whatever" "mod_mymod > Thingy"
1164      * would work.
1165      *
1166      * This method should return a list of {@link behat_component_named_selector} and
1167      * the docs on that class explain how it works.
1168      *
1169      * @return behat_component_named_selector[]
1170      */
1171     public static function get_exact_named_selectors(): array {
1172         return [];
1173     }
1175     /**
1176      * Return a list of the partial named selectors for the component.
1177      *
1178      * Like the exact named selectors above, but the locator only
1179      * needs to match part of the text. For example, the standard
1180      * "button" is a partial selector, so:
1181      *   When I click "Save" "button"
1182      * will activate "Save changes".
1183      *
1184      * @return behat_component_named_selector[]
1185      */
1186     public static function get_partial_named_selectors(): array {
1187         return [];
1188     }
1190     /**
1191      * Return a list of the Mink named replacements for the component.
1192      *
1193      * Named replacements allow you to define parts of an xpath that can be reused multiple times, or in multiple
1194      * xpaths.
1195      *
1196      * This method should return a list of {@link behat_component_named_replacement} and the docs on that class explain
1197      * how it works.
1198      *
1199      * @return behat_component_named_replacement[]
1200      */
1201     public static function get_named_replacements(): array {
1202         return [];
1203     }