[Summary view] [Print] [Text view]

   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/>.
  16  
  17  /**
  18   * Generic moodleforms field.
  19   *
  20   * @package    core_form
  21   * @category   test
  22   * @copyright  2012 David Monllaó
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  // NOTE: no MOODLE_INTERNAL test here, this file may be required by behat before including /config.php.
  27  
  28  use Behat\Mink\Session as Session,
  29      Behat\Mink\Element\NodeElement as NodeElement;
  30  
  31  /**
  32   * Representation of a form field.
  33   *
  34   * Basically an interface with Mink session.
  35   *
  36   * @package    core_form
  37   * @category   test
  38   * @copyright  2012 David Monllaó
  39   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  40   */
  41  class behat_form_field {
  42  
  43      /**
  44       * @var Session Behat session.
  45       */
  46      protected $session;
  47  
  48      /**
  49       * @var NodeElement The field DOM node to interact with.
  50       */
  51      protected $field;
  52  
  53      /**
  54       * @var string The field's locator.
  55       */
  56      protected $fieldlocator = false;
  57  
  58  
  59      /**
  60       * General constructor with the node and the session to interact with.
  61       *
  62       * @param Session $session Reference to Mink session to traverse/modify the page DOM.
  63       * @param NodeElement $fieldnode The field DOM node
  64       * @return void
  65       */
  66      public function __construct(Session $session, NodeElement $fieldnode) {
  67          $this->session = $session;
  68          $this->field = $fieldnode;
  69      }
  70  
  71      /**
  72       * Sets the value to a field.
  73       *
  74       * @param string $value
  75       * @return void
  76       */
  77      public function set_value($value) {
  78          // We delegate to the best guess, if we arrived here
  79          // using the generic behat_form_field is because we are
  80          // dealing with a fgroup element.
  81          $instance = $this->guess_type();
  82          return $instance->set_value($value);
  83      }
  84  
  85      /**
  86       * Returns the current value of the select element.
  87       *
  88       * @return string
  89       */
  90      public function get_value() {
  91          // We delegate to the best guess, if we arrived here
  92          // using the generic behat_form_field is because we are
  93          // dealing with a fgroup element.
  94          $instance = $this->guess_type();
  95          return $instance->get_value();
  96      }
  97  
  98      /**
  99       * Presses specific keyboard key.
 100       *
 101       * @param mixed  $char     could be either char ('b') or char-code (98)
 102       * @param string $modifier keyboard modifier (could be 'ctrl', 'alt', 'shift' or 'meta')
 103       */
 104      public function key_press($char, $modifier = null) {
 105          // We delegate to the best guess, if we arrived here
 106          // using the generic behat_form_field is because we are
 107          // dealing with a fgroup element.
 108          $instance = $this->guess_type();
 109          $instance->field->keyDown($char, $modifier);
 110          try {
 111              $instance->field->keyPress($char, $modifier);
 112              $instance->field->keyUp($char, $modifier);
 113          } catch (WebDriver\Exception $e) {
 114              // If the JS handler attached to keydown or keypress destroys the element
 115              // the later events may trigger errors because form element no longer exist
 116              // or is not visible. Ignore such exceptions here.
 117          }
 118      }
 119  
 120      /**
 121       * Generic match implementation
 122       *
 123       * Will work well with text-based fields, extension required
 124       * for most of the other cases.
 125       *
 126       * @param string $expectedvalue
 127       * @return bool The provided value matches the field value?
 128       */
 129      public function matches($expectedvalue) {
 130          // We delegate to the best guess, if we arrived here
 131          // using the generic behat_form_field is because we are
 132          // dealing with a fgroup element.
 133          $instance = $this->guess_type();
 134          return $instance->matches($expectedvalue);
 135      }
 136  
 137      /**
 138       * Guesses the element type we are dealing with in case is not a text-based element.
 139       *
 140       * This class is the generic field type, behat_field_manager::get_form_field()
 141       * should be able to find the appropiate class for the field type, but
 142       * in cases like moodle form group elements we can not find the type of
 143       * the field through the DOM so we also need to take care of the
 144       * different field types from here. If we need to deal with more complex
 145       * moodle form elements we will need to refactor this simple HTML elements
 146       * guess method.
 147       *
 148       * @return behat_form_field
 149       */
 150      private function guess_type() {
 151          global $CFG;
 152  
 153          // We default to the text-based field if nothing was detected.
 154          if (!$type = behat_field_manager::guess_field_type($this->field, $this->session)) {
 155              $type = 'text';
 156          }
 157  
 158          $classname = 'behat_form_' . $type;
 159          $classpath = $CFG->dirroot . '/lib/behat/form_field/' . $classname . '.php';
 160          require_once($classpath);
 161          return new $classname($this->session, $this->field);
 162      }
 163  
 164      /**
 165       * Returns whether the scenario is running in a browser that can run Javascript or not.
 166       *
 167       * @return bool
 168       */
 169      protected function running_javascript() {
 170          return get_class($this->session->getDriver()) !== 'Behat\Mink\Driver\GoutteDriver';
 171      }
 172  
 173      /**
 174       * Gets the field internal id used by selenium wire protocol.
 175       *
 176       * Only available when running_javascript().
 177       *
 178       * @throws coding_exception
 179       * @return int
 180       */
 181      protected function get_internal_field_id() {
 182  
 183          if (!$this->running_javascript()) {
 184              throw new coding_exception('You can only get an internal ID using the selenium driver.');
 185          }
 186  
 187          return $this->session->getDriver()->getWebDriverSession()->element('xpath', $this->field->getXPath())->getID();
 188      }
 189  
 190      /**
 191       * Checks if the provided text matches the field value.
 192       *
 193       * @param string $expectedvalue
 194       * @return bool
 195       */
 196      protected function text_matches($expectedvalue) {
 197          if (trim($expectedvalue) != trim($this->get_value())) {
 198              return false;
 199          }
 200          return true;
 201      }
 202  
 203      /**
 204       * Gets the field locator.
 205       *
 206       * Defaults to the field label but you can
 207       * specify other locators if you are interested.
 208       *
 209       * Public visibility as in most cases will be hard to
 210       * use this method in a generic way, as fields can
 211       * be selected using multiple ways (label, id, name...).
 212       *
 213       * @throws coding_exception
 214       * @param string $locatortype
 215       * @return string
 216       */
 217      protected function get_field_locator($locatortype = false) {
 218  
 219          if (!empty($this->fieldlocator)) {
 220              return $this->fieldlocator;
 221          }
 222  
 223          $fieldid = $this->field->getAttribute('id');
 224  
 225          // Defaults to label.
 226          if ($locatortype == 'label' || $locatortype == false) {
 227  
 228              $labelnode = $this->session->getPage()->find('xpath', '//label[@for="' . $fieldid . '"]');
 229  
 230              // Exception only if $locatortype was specified.
 231              if (!$labelnode && $locatortype == 'label') {
 232                  throw new coding_exception('Field with "' . $fieldid . '" id does not have a label.');
 233              }
 234  
 235              $this->fieldlocator = $labelnode->getText();
 236          }
 237  
 238          // Let's look for the name as a second option (more popular than
 239          // id's when pointing to fields).
 240          if (($locatortype == 'name' || $locatortype == false) &&
 241                  empty($this->fieldlocator)) {
 242  
 243              $name = $this->field->getAttribute('name');
 244  
 245              // Exception only if $locatortype was specified.
 246              if (!$name && $locatortype == 'name') {
 247                  throw new coding_exception('Field with "' . $fieldid . '" id does not have a name attribute.');
 248              }
 249  
 250              $this->fieldlocator = $name;
 251          }
 252  
 253          // Otherwise returns the id if no specific locator type was provided.
 254          if (empty($this->fieldlocator)) {
 255              $this->fieldlocator = $fieldid;
 256          }
 257  
 258          return $this->fieldlocator;
 259      }
 260  }