www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/simpletest/src/AssertContentTrait.php

   1 <?php
   2
   3 namespace Drupal\simpletest;
   4
   5 use Drupal\Component\Serialization\Json;
   6 use Drupal\Component\Utility\Html;
   7 use Drupal\Component\Utility\SafeMarkup;
   8 use Drupal\Component\Utility\Xss;
   9 use Drupal\Core\Render\RenderContext;
  10 use Symfony\Component\CssSelector\CssSelectorConverter;
  11
  12 /**
  13  * Provides test methods to assert content.
  14  */
  15 trait AssertContentTrait {
  16
  17   /**
  18    * The current raw content.
  19    *
  20    * @var string
  21    */
  22   protected $content;
  23
  24   /**
  25    * The plain-text content of raw $content (text nodes).
  26    *
  27    * @var string
  28    */
  29   protected $plainTextContent;
  30
  31   /**
  32    * The drupalSettings value from the current raw $content.
  33    *
  34    * drupalSettings refers to the drupalSettings JavaScript variable.
  35    *
  36    * @var array
  37    */
  38   protected $drupalSettings;
  39
  40   /**
  41    * The XML structure parsed from the current raw $content.
  42    *
  43    * @var \SimpleXMLElement
  44    */
  45   protected $elements;
  46
  47   /**
  48    * Gets the current raw content.
  49    */
  50   protected function getRawContent() {
  51     return $this->content;
  52   }
  53
  54   /**
  55    * Sets the raw content (e.g. HTML).
  56    *
  57    * @param string $content
  58    *   The raw content to set.
  59    */
  60   protected function setRawContent($content) {
  61     $this->content = $content;
  62     $this->plainTextContent = NULL;
  63     $this->elements = NULL;
  64     $this->drupalSettings = [];
  65     if (preg_match('@<script type="application/json" data-drupal-selector="drupal-settings-json">([^<]*)</script>@', $content, $matches)) {
  66       $this->drupalSettings = Json::decode($matches[1]);
  67     }
  68   }
  69
  70   /**
  71    * Retrieves the plain-text content from the current raw content.
  72    */
  73   protected function getTextContent() {
  74     if (!isset($this->plainTextContent)) {
  75       $raw_content = $this->getRawContent();
  76       // Strip everything between the HEAD tags.
  77       $raw_content = preg_replace('@<head>(.+?)</head>@si', '', $raw_content);
  78       $this->plainTextContent = Xss::filter($raw_content, []);
  79     }
  80     return $this->plainTextContent;
  81   }
  82
  83   /**
  84    * Removes all white-space between HTML tags from the raw content.
  85    *
  86    * White-space is only removed if there are no non-white-space characters
  87    * between HTML tags.
  88    *
  89    * Use this (once) after performing an operation that sets new raw content,
  90    * and when you want to use e.g. assertText() but ignore potential white-space
  91    * caused by HTML output templates.
  92    */
  93   protected function removeWhiteSpace() {
  94     $this->content = preg_replace('@>\s+<@', '><', $this->content);
  95     $this->plainTextContent = NULL;
  96     $this->elements = NULL;
  97   }
  98
  99   /**
 100    * Gets the value of drupalSettings for the currently-loaded page.
 101    *
 102    * drupalSettings refers to the drupalSettings JavaScript variable.
 103    */
 104   protected function getDrupalSettings() {
 105     return $this->drupalSettings;
 106   }
 107
 108   /**
 109    * Sets the value of drupalSettings for the currently-loaded page.
 110    *
 111    * drupalSettings refers to the drupalSettings JavaScript variable.
 112    */
 113   protected function setDrupalSettings($settings) {
 114     $this->drupalSettings = $settings;
 115   }
 116
 117   /**
 118    * Parse content returned from curlExec using DOM and SimpleXML.
 119    *
 120    * @return \SimpleXMLElement|false
 121    *   A SimpleXMLElement or FALSE on failure.
 122    */
 123   protected function parse() {
 124     if (!isset($this->elements)) {
 125       // DOM can load HTML soup. But, HTML soup can throw warnings, suppress
 126       // them.
 127       $html_dom = new \DOMDocument();
 128       @$html_dom->loadHTML('<?xml encoding="UTF-8">' . $this->getRawContent());
 129       if ($html_dom) {
 130         $this->pass(SafeMarkup::format('Valid HTML found on "@path"', ['@path' => $this->getUrl()]), 'Browser');
 131         // It's much easier to work with simplexml than DOM, luckily enough
 132         // we can just simply import our DOM tree.
 133         $this->elements = simplexml_import_dom($html_dom);
 134       }
 135     }
 136     if ($this->elements === FALSE) {
 137       $this->fail('Parsed page successfully.', 'Browser');
 138     }
 139
 140     return $this->elements;
 141   }
 142
 143   /**
 144    * Get the current URL from the cURL handler.
 145    *
 146    * @return string
 147    *   The current URL.
 148    */
 149   protected function getUrl() {
 150     return isset($this->url) ? $this->url : 'no-url';
 151   }
 152
 153   /**
 154    * Builds an XPath query.
 155    *
 156    * Builds an XPath query by replacing placeholders in the query by the value
 157    * of the arguments.
 158    *
 159    * XPath 1.0 (the version supported by libxml2, the underlying XML library
 160    * used by PHP) doesn't support any form of quotation. This function
 161    * simplifies the building of XPath expression.
 162    *
 163    * @param string $xpath
 164    *   An XPath query, possibly with placeholders in the form ':name'.
 165    * @param array $args
 166    *   An array of arguments with keys in the form ':name' matching the
 167    *   placeholders in the query. The values may be either strings or numeric
 168    *   values.
 169    *
 170    * @return string
 171    *   An XPath query with arguments replaced.
 172    */
 173   protected function buildXPathQuery($xpath, array $args = []) {
 174     // Replace placeholders.
 175     foreach ($args as $placeholder => $value) {
 176       // Cast MarkupInterface objects to string.
 177       if (is_object($value)) {
 178         $value = (string) $value;
 179       }
 180       // XPath 1.0 doesn't support a way to escape single or double quotes in a
 181       // string literal. We split double quotes out of the string, and encode
 182       // them separately.
 183       if (is_string($value)) {
 184         // Explode the text at the quote characters.
 185         $parts = explode('"', $value);
 186
 187         // Quote the parts.
 188         foreach ($parts as &$part) {
 189           $part = '"' . $part . '"';
 190         }
 191
 192         // Return the string.
 193         $value = count($parts) > 1 ? 'concat(' . implode(', \'"\', ', $parts) . ')' : $parts[0];
 194       }
 195
 196       // Use preg_replace_callback() instead of preg_replace() to prevent the
 197       // regular expression engine from trying to substitute backreferences.
 198       $replacement = function ($matches) use ($value) {
 199         return $value;
 200       };
 201       $xpath = preg_replace_callback('/' . preg_quote($placeholder) . '\b/', $replacement, $xpath);
 202     }
 203     return $xpath;
 204   }
 205
 206   /**
 207    * Performs an xpath search on the contents of the internal browser.
 208    *
 209    * The search is relative to the root element (HTML tag normally) of the page.
 210    *
 211    * @param string $xpath
 212    *   The xpath string to use in the search.
 213    * @param array $arguments
 214    *   An array of arguments with keys in the form ':name' matching the
 215    *   placeholders in the query. The values may be either strings or numeric
 216    *   values.
 217    *
 218    * @return \SimpleXMLElement[]|bool
 219    *   The return value of the xpath search or FALSE on failure. For details on
 220    *   the xpath string format and return values see the SimpleXML
 221    *   documentation.
 222    *
 223    * @see http://php.net/manual/function.simplexml-element-xpath.php
 224    */
 225   protected function xpath($xpath, array $arguments = []) {
 226     if ($this->parse()) {
 227       $xpath = $this->buildXPathQuery($xpath, $arguments);
 228       $result = $this->elements->xpath($xpath);
 229       // Some combinations of PHP / libxml versions return an empty array
 230       // instead of the documented FALSE. Forcefully convert any falsish values
 231       // to an empty array to allow foreach(...) constructions.
 232       return $result ?: [];
 233     }
 234     return FALSE;
 235   }
 236
 237   /**
 238    * Searches elements using a CSS selector in the raw content.
 239    *
 240    * The search is relative to the root element (HTML tag normally) of the page.
 241    *
 242    * @param string $selector
 243    *   CSS selector to use in the search.
 244    *
 245    * @return \SimpleXMLElement[]
 246    *   The return value of the XPath search performed after converting the CSS
 247    *   selector to an XPath selector.
 248    */
 249   protected function cssSelect($selector) {
 250     return $this->xpath((new CssSelectorConverter())->toXPath($selector));
 251   }
 252
 253   /**
 254    * Get all option elements, including nested options, in a select.
 255    *
 256    * @param \SimpleXMLElement $element
 257    *   The element for which to get the options.
 258    *
 259    * @return \SimpleXmlElement[]
 260    *   Option elements in select.
 261    */
 262   protected function getAllOptions(\SimpleXMLElement $element) {
 263     $options = [];
 264     // Add all options items.
 265     foreach ($element->option as $option) {
 266       $options[] = $option;
 267     }
 268
 269     // Search option group children.
 270     if (isset($element->optgroup)) {
 271       foreach ($element->optgroup as $group) {
 272         $options = array_merge($options, $this->getAllOptions($group));
 273       }
 274     }
 275     return $options;
 276   }
 277
 278   /**
 279    * Passes if a link with the specified label is found.
 280    *
 281    * An optional link index may be passed.
 282    *
 283    * @param string|\Drupal\Component\Render\MarkupInterface $label
 284    *   Text between the anchor tags.
 285    * @param int $index
 286    *   Link position counting from zero.
 287    * @param string $message
 288    *   (optional) A message to display with the assertion. Do not translate
 289    *   messages: use strtr() to embed variables in the message text, not
 290    *   t(). If left blank, a default message will be displayed.
 291    * @param string $group
 292    *   (optional) The group this message is in, which is displayed in a column
 293    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 294    *   translate this string. Defaults to 'Other'; most tests do not override
 295    *   this default.
 296    *
 297    * @return bool
 298    *   TRUE if the assertion succeeded, FALSE otherwise.
 299    */
 300   protected function assertLink($label, $index = 0, $message = '', $group = 'Other') {
 301     // Cast MarkupInterface objects to string.
 302     $label = (string) $label;
 303     $links = $this->xpath('//a[normalize-space(text())=:label]', [':label' => $label]);
 304     $message = ($message ? $message : strtr('Link with label %label found.', ['%label' => $label]));
 305     return $this->assert(isset($links[$index]), $message, $group);
 306   }
 307
 308   /**
 309    * Passes if a link with the specified label is not found.
 310    *
 311    * @param string|\Drupal\Component\Render\MarkupInterface $label
 312    *   Text between the anchor tags.
 313    * @param string $message
 314    *   (optional) A message to display with the assertion. Do not translate
 315    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 316    *   variables in the message text, not t(). If left blank, a default message
 317    *   will be displayed.
 318    * @param string $group
 319    *   (optional) The group this message is in, which is displayed in a column
 320    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 321    *   translate this string. Defaults to 'Other'; most tests do not override
 322    *   this default.
 323    *
 324    * @return bool
 325    *   TRUE if the assertion succeeded, FALSE otherwise.
 326    */
 327   protected function assertNoLink($label, $message = '', $group = 'Other') {
 328     // Cast MarkupInterface objects to string.
 329     $label = (string) $label;
 330     $links = $this->xpath('//a[normalize-space(text())=:label]', [':label' => $label]);
 331     $message = ($message ? $message : SafeMarkup::format('Link with label %label not found.', ['%label' => $label]));
 332     return $this->assert(empty($links), $message, $group);
 333   }
 334
 335   /**
 336    * Passes if a link containing a given href (part) is found.
 337    *
 338    * @param string $href
 339    *   The full or partial value of the 'href' attribute of the anchor tag.
 340    * @param string $index
 341    *   Link position counting from zero.
 342    * @param string $message
 343    *   (optional) A message to display with the assertion. Do not translate
 344    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 345    *   variables in the message text, not t(). If left blank, a default message
 346    *   will be displayed.
 347    * @param string $group
 348    *   (optional) The group this message is in, which is displayed in a column
 349    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 350    *   translate this string. Defaults to 'Other'; most tests do not override
 351    *   this default.
 352    *
 353    * @return bool
 354    *   TRUE if the assertion succeeded, FALSE otherwise.
 355    */
 356   protected function assertLinkByHref($href, $index = 0, $message = '', $group = 'Other') {
 357     $links = $this->xpath('//a[contains(@href, :href)]', [':href' => $href]);
 358     $message = ($message ? $message : SafeMarkup::format('Link containing href %href found.', ['%href' => $href]));
 359     return $this->assert(isset($links[$index]), $message, $group);
 360   }
 361
 362   /**
 363    * Passes if a link containing a given href (part) is not found.
 364    *
 365    * @param string $href
 366    *   The full or partial value of the 'href' attribute of the anchor tag.
 367    * @param string $message
 368    *   (optional) A message to display with the assertion. Do not translate
 369    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 370    *   variables in the message text, not t(). If left blank, a default message
 371    *   will be displayed.
 372    * @param string $group
 373    *   (optional) The group this message is in, which is displayed in a column
 374    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 375    *   translate this string. Defaults to 'Other'; most tests do not override
 376    *   this default.
 377    *
 378    * @return bool
 379    *   TRUE if the assertion succeeded, FALSE otherwise.
 380    */
 381   protected function assertNoLinkByHref($href, $message = '', $group = 'Other') {
 382     $links = $this->xpath('//a[contains(@href, :href)]', [':href' => $href]);
 383     $message = ($message ? $message : SafeMarkup::format('No link containing href %href found.', ['%href' => $href]));
 384     return $this->assert(empty($links), $message, $group);
 385   }
 386
 387   /**
 388    * Passes if a link containing a given href is not found in the main region.
 389    *
 390    * @param string $href
 391    *   The full or partial value of the 'href' attribute of the anchor tag.
 392    * @param string $message
 393    *   (optional) A message to display with the assertion. Do not translate
 394    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 395    *   variables in the message text, not t(). If left blank, a default message
 396    *   will be displayed.
 397    * @param string $group
 398    *   (optional) The group this message is in, which is displayed in a column
 399    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 400    *   translate this string. Defaults to 'Other'; most tests do not override
 401    *   this default.
 402    *
 403    * @return bool
 404    *   TRUE if the assertion succeeded, FALSE otherwise.
 405    */
 406   protected function assertNoLinkByHrefInMainRegion($href, $message = '', $group = 'Other') {
 407     $links = $this->xpath('//main//a[contains(@href, :href)]', [':href' => $href]);
 408     $message = ($message ? $message : SafeMarkup::format('No link containing href %href found.', ['%href' => $href]));
 409     return $this->assert(empty($links), $message, $group);
 410   }
 411
 412   /**
 413    * Passes if the raw text IS found on the loaded page, fail otherwise.
 414    *
 415    * Raw text refers to the raw HTML that the page generated.
 416    *
 417    * @param string $raw
 418    *   Raw (HTML) string to look for.
 419    * @param string $message
 420    *   (optional) A message to display with the assertion. Do not translate
 421    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 422    *   variables in the message text, not t(). If left blank, a default message
 423    *   will be displayed.
 424    * @param string $group
 425    *   (optional) The group this message is in, which is displayed in a column
 426    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 427    *   translate this string. Defaults to 'Other'; most tests do not override
 428    *   this default.
 429    *
 430    * @return bool
 431    *   TRUE on pass, FALSE on fail.
 432    */
 433   protected function assertRaw($raw, $message = '', $group = 'Other') {
 434     if (!$message) {
 435       $message = 'Raw "' . Html::escape($raw) . '" found';
 436     }
 437     return $this->assert(strpos($this->getRawContent(), (string) $raw) !== FALSE, $message, $group);
 438   }
 439
 440   /**
 441    * Passes if the raw text is NOT found on the loaded page, fail otherwise.
 442    *
 443    * Raw text refers to the raw HTML that the page generated.
 444    *
 445    * @param string $raw
 446    *   Raw (HTML) string to look for.
 447    * @param string $message
 448    *   (optional) A message to display with the assertion. Do not translate
 449    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 450    *   variables in the message text, not t(). If left blank, a default message
 451    *   will be displayed.
 452    * @param string $group
 453    *   (optional) The group this message is in, which is displayed in a column
 454    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 455    *   translate this string. Defaults to 'Other'; most tests do not override
 456    *   this default.
 457    *
 458    * @return bool
 459    *   TRUE on pass, FALSE on fail.
 460    */
 461   protected function assertNoRaw($raw, $message = '', $group = 'Other') {
 462     if (!$message) {
 463       $message = 'Raw "' . Html::escape($raw) . '" not found';
 464     }
 465     return $this->assert(strpos($this->getRawContent(), (string) $raw) === FALSE, $message, $group);
 466   }
 467
 468   /**
 469    * Passes if the raw text IS found escaped on the loaded page, fail otherwise.
 470    *
 471    * Raw text refers to the raw HTML that the page generated.
 472    *
 473    * @param string $raw
 474    *   Raw (HTML) string to look for.
 475    * @param string $message
 476    *   (optional) A message to display with the assertion. Do not translate
 477    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 478    *   variables in the message text, not t(). If left blank, a default message
 479    *   will be displayed.
 480    * @param string $group
 481    *   (optional) The group this message is in, which is displayed in a column
 482    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 483    *   translate this string. Defaults to 'Other'; most tests do not override
 484    *   this default.
 485    *
 486    * @return bool
 487    *   TRUE on pass, FALSE on fail.
 488    */
 489   protected function assertEscaped($raw, $message = '', $group = 'Other') {
 490     if (!$message) {
 491       $message = 'Escaped "' . Html::escape($raw) . '" found';
 492     }
 493     return $this->assert(strpos($this->getRawContent(), Html::escape($raw)) !== FALSE, $message, $group);
 494   }
 495
 496   /**
 497    * Passes if the raw text IS NOT found escaped on the loaded page, fail
 498    * otherwise.
 499    *
 500    * Raw text refers to the raw HTML that the page generated.
 501    *
 502    * @param string $raw
 503    *   Raw (HTML) string to look for.
 504    * @param string $message
 505    *   (optional) A message to display with the assertion. Do not translate
 506    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 507    *   variables in the message text, not t(). If left blank, a default message
 508    *   will be displayed.
 509    * @param string $group
 510    *   (optional) The group this message is in, which is displayed in a column
 511    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 512    *   translate this string. Defaults to 'Other'; most tests do not override
 513    *   this default.
 514    *
 515    * @return bool
 516    *   TRUE on pass, FALSE on fail.
 517    */
 518   protected function assertNoEscaped($raw, $message = '', $group = 'Other') {
 519     if (!$message) {
 520       $message = 'Escaped "' . Html::escape($raw) . '" not found';
 521     }
 522     return $this->assert(strpos($this->getRawContent(), Html::escape($raw)) === FALSE, $message, $group);
 523   }
 524
 525   /**
 526    * Passes if the page (with HTML stripped) contains the text.
 527    *
 528    * Note that stripping HTML tags also removes their attributes, such as
 529    * the values of text fields.
 530    *
 531    * @param string $text
 532    *   Plain text to look for.
 533    * @param string $message
 534    *   (optional) A message to display with the assertion. Do not translate
 535    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 536    *   variables in the message text, not t(). If left blank, a default message
 537    *   will be displayed.
 538    * @param string $group
 539    *   (optional) The group this message is in, which is displayed in a column
 540    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 541    *   translate this string. Defaults to 'Other'; most tests do not override
 542    *   this default.
 543    *
 544    * @return bool
 545    *   TRUE on pass, FALSE on fail.
 546    *
 547    * @see \Drupal\simpletest\AssertContentTrait::assertRaw()
 548    */
 549   protected function assertText($text, $message = '', $group = 'Other') {
 550     return $this->assertTextHelper($text, $message, $group, FALSE);
 551   }
 552
 553   /**
 554    * Passes if the page (with HTML stripped) does not contains the text.
 555    *
 556    * Note that stripping HTML tags also removes their attributes, such as
 557    * the values of text fields.
 558    *
 559    * @param string $text
 560    *   Plain text to look for.
 561    * @param string $message
 562    *   (optional) A message to display with the assertion. Do not translate
 563    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 564    *   variables in the message text, not t(). If left blank, a default message
 565    *   will be displayed.
 566    * @param string $group
 567    *   (optional) The group this message is in, which is displayed in a column
 568    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 569    *   translate this string. Defaults to 'Other'; most tests do not override
 570    *   this default.
 571    *
 572    * @return bool
 573    *   TRUE on pass, FALSE on fail.
 574    *
 575    * @see \Drupal\simpletest\AssertContentTrait::assertNoRaw()
 576    */
 577   protected function assertNoText($text, $message = '', $group = 'Other') {
 578     return $this->assertTextHelper($text, $message, $group, TRUE);
 579   }
 580
 581   /**
 582    * Helper for assertText and assertNoText.
 583    *
 584    * It is not recommended to call this function directly.
 585    *
 586    * @param string $text
 587    *   Plain text to look for.
 588    * @param string $message
 589    *   (optional) A message to display with the assertion. Do not translate
 590    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 591    *   variables in the message text, not t(). If left blank, a default message
 592    *   will be displayed.
 593    * @param string $group
 594    *   (optional) The group this message is in, which is displayed in a column
 595    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 596    *   translate this string. Defaults to 'Other'; most tests do not override
 597    *   this default. Defaults to 'Other'.
 598    * @param bool $not_exists
 599    *   (optional) TRUE if this text should not exist, FALSE if it should.
 600    *   Defaults to TRUE.
 601    *
 602    * @return bool
 603    *   TRUE on pass, FALSE on fail.
 604    */
 605   protected function assertTextHelper($text, $message = '', $group = 'Other', $not_exists = TRUE) {
 606     if (!$message) {
 607       $message = !$not_exists ? SafeMarkup::format('"@text" found', ['@text' => $text]) : SafeMarkup::format('"@text" not found', ['@text' => $text]);
 608     }
 609     return $this->assert($not_exists == (strpos($this->getTextContent(), (string) $text) === FALSE), $message, $group);
 610   }
 611
 612   /**
 613    * Passes if the text is found ONLY ONCE on the text version of the page.
 614    *
 615    * The text version is the equivalent of what a user would see when viewing
 616    * through a web browser. In other words the HTML has been filtered out of
 617    * the contents.
 618    *
 619    * @param string|\Drupal\Component\Render\MarkupInterface $text
 620    *   Plain text to look for.
 621    * @param string $message
 622    *   (optional) A message to display with the assertion. Do not translate
 623    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 624    *   variables in the message text, not t(). If left blank, a default message
 625    *   will be displayed.
 626    * @param string $group
 627    *   (optional) The group this message is in, which is displayed in a column
 628    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 629    *   translate this string. Defaults to 'Other'; most tests do not override
 630    *   this default.
 631    *
 632    * @return bool
 633    *   TRUE on pass, FALSE on fail.
 634    */
 635   protected function assertUniqueText($text, $message = '', $group = 'Other') {
 636     return $this->assertUniqueTextHelper($text, $message, $group, TRUE);
 637   }
 638
 639   /**
 640    * Passes if the text is found MORE THAN ONCE on the text version of the page.
 641    *
 642    * The text version is the equivalent of what a user would see when viewing
 643    * through a web browser. In other words the HTML has been filtered out of
 644    * the contents.
 645    *
 646    * @param string|\Drupal\Component\Render\MarkupInterface $text
 647    *   Plain text to look for.
 648    * @param string $message
 649    *   (optional) A message to display with the assertion. Do not translate
 650    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 651    *   variables in the message text, not t(). If left blank, a default message
 652    *   will be displayed.
 653    * @param string $group
 654    *   (optional) The group this message is in, which is displayed in a column
 655    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 656    *   translate this string. Defaults to 'Other'; most tests do not override
 657    *   this default.
 658    *
 659    * @return bool
 660    *   TRUE on pass, FALSE on fail.
 661    */
 662   protected function assertNoUniqueText($text, $message = '', $group = 'Other') {
 663     return $this->assertUniqueTextHelper($text, $message, $group, FALSE);
 664   }
 665
 666   /**
 667    * Helper for assertUniqueText and assertNoUniqueText.
 668    *
 669    * It is not recommended to call this function directly.
 670    *
 671    * @param string|\Drupal\Component\Render\MarkupInterface $text
 672    *   Plain text to look for.
 673    * @param string $message
 674    *   (optional) A message to display with the assertion. Do not translate
 675    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 676    *   variables in the message text, not t(). If left blank, a default message
 677    *   will be displayed.
 678    * @param string $group
 679    *   (optional) The group this message is in, which is displayed in a column
 680    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 681    *   translate this string. Defaults to 'Other'; most tests do not override
 682    *   this default. Defaults to 'Other'.
 683    * @param bool $be_unique
 684    *   (optional) TRUE if this text should be found only once, FALSE if it
 685    *   should be found more than once. Defaults to FALSE.
 686    *
 687    * @return bool
 688    *   TRUE on pass, FALSE on fail.
 689    */
 690   protected function assertUniqueTextHelper($text, $message = '', $group = 'Other', $be_unique = FALSE) {
 691     // Cast MarkupInterface objects to string.
 692     $text = (string) $text;
 693     if (!$message) {
 694       $message = '"' . $text . '"' . ($be_unique ? ' found only once' : ' found more than once');
 695     }
 696     $first_occurrence = strpos($this->getTextContent(), $text);
 697     if ($first_occurrence === FALSE) {
 698       return $this->assert(FALSE, $message, $group);
 699     }
 700     $offset = $first_occurrence + strlen($text);
 701     $second_occurrence = strpos($this->getTextContent(), $text, $offset);
 702     return $this->assert($be_unique == ($second_occurrence === FALSE), $message, $group);
 703   }
 704
 705   /**
 706    * Triggers a pass if the Perl regex pattern is found in the raw content.
 707    *
 708    * @param string $pattern
 709    *   Perl regex to look for including the regex delimiters.
 710    * @param string $message
 711    *   (optional) A message to display with the assertion. Do not translate
 712    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 713    *   variables in the message text, not t(). If left blank, a default message
 714    *   will be displayed.
 715    * @param string $group
 716    *   (optional) The group this message is in, which is displayed in a column
 717    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 718    *   translate this string. Defaults to 'Other'; most tests do not override
 719    *   this default.
 720    *
 721    * @return bool
 722    *   TRUE on pass, FALSE on fail.
 723    */
 724   protected function assertPattern($pattern, $message = '', $group = 'Other') {
 725     if (!$message) {
 726       $message = SafeMarkup::format('Pattern "@pattern" found', ['@pattern' => $pattern]);
 727     }
 728     return $this->assert((bool) preg_match($pattern, $this->getRawContent()), $message, $group);
 729   }
 730
 731   /**
 732    * Triggers a pass if the perl regex pattern is not found in raw content.
 733    *
 734    * @param string $pattern
 735    *   Perl regex to look for including the regex delimiters.
 736    * @param string $message
 737    *   (optional) A message to display with the assertion. Do not translate
 738    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 739    *   variables in the message text, not t(). If left blank, a default message
 740    *   will be displayed.
 741    * @param string $group
 742    *   (optional) The group this message is in, which is displayed in a column
 743    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 744    *   translate this string. Defaults to 'Other'; most tests do not override
 745    *   this default.
 746    *
 747    * @return bool
 748    *   TRUE on pass, FALSE on fail.
 749    */
 750   protected function assertNoPattern($pattern, $message = '', $group = 'Other') {
 751     if (!$message) {
 752       $message = SafeMarkup::format('Pattern "@pattern" not found', ['@pattern' => $pattern]);
 753     }
 754     return $this->assert(!preg_match($pattern, $this->getRawContent()), $message, $group);
 755   }
 756
 757   /**
 758    * Asserts that a Perl regex pattern is found in the plain-text content.
 759    *
 760    * @param string $pattern
 761    *   Perl regex to look for including the regex delimiters.
 762    * @param string $message
 763    *   (optional) A message to display with the assertion.
 764    * @param string $group
 765    *   (optional) The group this message is in, which is displayed in a column
 766    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 767    *   translate this string. Defaults to 'Other'; most tests do not override
 768    *   this default.
 769    *
 770    * @return bool
 771    *   TRUE on pass, FALSE on failure.
 772    */
 773   protected function assertTextPattern($pattern, $message = NULL, $group = 'Other') {
 774     if (!isset($message)) {
 775       $message = SafeMarkup::format('Pattern "@pattern" found', ['@pattern' => $pattern]);
 776     }
 777     return $this->assert((bool) preg_match($pattern, $this->getTextContent()), $message, $group);
 778   }
 779
 780   /**
 781    * Pass if the page title is the given string.
 782    *
 783    * @param string $title
 784    *   The string the title should be.
 785    * @param string $message
 786    *   (optional) A message to display with the assertion. Do not translate
 787    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 788    *   variables in the message text, not t(). If left blank, a default message
 789    *   will be displayed.
 790    * @param string $group
 791    *   (optional) The group this message is in, which is displayed in a column
 792    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 793    *   translate this string. Defaults to 'Other'; most tests do not override
 794    *   this default.
 795    *
 796    * @return bool
 797    *   TRUE on pass, FALSE on fail.
 798    */
 799   protected function assertTitle($title, $message = '', $group = 'Other') {
 800     // Don't use xpath as it messes with HTML escaping.
 801     preg_match('@<title>(.*)</title>@', $this->getRawContent(), $matches);
 802     if (isset($matches[1])) {
 803       $actual = $matches[1];
 804       $actual = $this->castSafeStrings($actual);
 805       $title = $this->castSafeStrings($title);
 806       if (!$message) {
 807         $message = SafeMarkup::format('Page title @actual is equal to @expected.', [
 808           '@actual' => var_export($actual, TRUE),
 809           '@expected' => var_export($title, TRUE),
 810         ]);
 811       }
 812       return $this->assertEqual($actual, $title, $message, $group);
 813     }
 814     return $this->fail('No title element found on the page.');
 815   }
 816
 817   /**
 818    * Pass if the page title is not the given string.
 819    *
 820    * @param string $title
 821    *   The string the title should not be.
 822    * @param string $message
 823    *   (optional) A message to display with the assertion. Do not translate
 824    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 825    *   variables in the message text, not t(). If left blank, a default message
 826    *   will be displayed.
 827    * @param string $group
 828    *   (optional) The group this message is in, which is displayed in a column
 829    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 830    *   translate this string. Defaults to 'Other'; most tests do not override
 831    *   this default.
 832    *
 833    * @return bool
 834    *   TRUE on pass, FALSE on fail.
 835    */
 836   protected function assertNoTitle($title, $message = '', $group = 'Other') {
 837     $actual = (string) current($this->xpath('//title'));
 838     if (!$message) {
 839       $message = SafeMarkup::format('Page title @actual is not equal to @unexpected.', [
 840         '@actual' => var_export($actual, TRUE),
 841         '@unexpected' => var_export($title, TRUE),
 842       ]);
 843     }
 844     return $this->assertNotEqual($actual, $title, $message, $group);
 845   }
 846
 847   /**
 848    * Asserts themed output.
 849    *
 850    * @param string $callback
 851    *   The name of the theme hook to invoke; e.g. 'links' for links.html.twig.
 852    * @param string $variables
 853    *   An array of variables to pass to the theme function.
 854    * @param string $expected
 855    *   The expected themed output string.
 856    * @param string $message
 857    *   (optional) A message to display with the assertion. Do not translate
 858    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 859    *   variables in the message text, not t(). If left blank, a default message
 860    *   will be displayed.
 861    * @param string $group
 862    *   (optional) The group this message is in, which is displayed in a column
 863    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 864    *   translate this string. Defaults to 'Other'; most tests do not override
 865    *   this default.
 866    *
 867    * @return bool
 868    *   TRUE on pass, FALSE on fail.
 869    */
 870   protected function assertThemeOutput($callback, array $variables = [], $expected = '', $message = '', $group = 'Other') {
 871     /** @var \Drupal\Core\Render\RendererInterface $renderer */
 872     $renderer = \Drupal::service('renderer');
 873
 874     // The string cast is necessary because theme functions return
 875     // MarkupInterface objects. This means we can assert that $expected
 876     // matches the theme output without having to worry about 0 == ''.
 877     $output = (string) $renderer->executeInRenderContext(new RenderContext(), function() use ($callback, $variables) {
 878       return \Drupal::theme()->render($callback, $variables);
 879     });
 880     $this->verbose(
 881       '<hr />' . 'Result:' . '<pre>' . Html::escape(var_export($output, TRUE)) . '</pre>'
 882       . '<hr />' . 'Expected:' . '<pre>' . Html::escape(var_export($expected, TRUE)) . '</pre>'
 883       . '<hr />' . $output
 884     );
 885     if (!$message) {
 886       $message = '%callback rendered correctly.';
 887     }
 888     $message = format_string($message, ['%callback' => 'theme_' . $callback . '()']);
 889     return $this->assertIdentical($output, $expected, $message, $group);
 890   }
 891
 892   /**
 893    * Asserts that a field exists in the current page with a given Xpath result.
 894    *
 895    * @param \SimpleXmlElement[] $fields
 896    *   Xml elements.
 897    * @param string $value
 898    *   (optional) Value of the field to assert. You may pass in NULL (default) to skip
 899    *   checking the actual value, while still checking that the field exists.
 900    * @param string $message
 901    *   (optional) A message to display with the assertion. Do not translate
 902    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 903    *   variables in the message text, not t(). If left blank, a default message
 904    *   will be displayed.
 905    * @param string $group
 906    *   (optional) The group this message is in, which is displayed in a column
 907    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 908    *   translate this string. Defaults to 'Other'; most tests do not override
 909    *   this default.
 910    *
 911    * @return bool
 912    *   TRUE on pass, FALSE on fail.
 913    */
 914   protected function assertFieldsByValue($fields, $value = NULL, $message = '', $group = 'Other') {
 915     // If value specified then check array for match.
 916     $found = TRUE;
 917     if (isset($value)) {
 918       $found = FALSE;
 919       if ($fields) {
 920         foreach ($fields as $field) {
 921           if (isset($field['value']) && $field['value'] == $value) {
 922             // Input element with correct value.
 923             $found = TRUE;
 924           }
 925           elseif (isset($field->option) || isset($field->optgroup)) {
 926             // Select element found.
 927             $selected = $this->getSelectedItem($field);
 928             if ($selected === FALSE) {
 929               // No item selected so use first item.
 930               $items = $this->getAllOptions($field);
 931               if (!empty($items) && $items[0]['value'] == $value) {
 932                 $found = TRUE;
 933               }
 934             }
 935             elseif ($selected == $value) {
 936               $found = TRUE;
 937             }
 938           }
 939           elseif ((string) $field == $value) {
 940             // Text area with correct text.
 941             $found = TRUE;
 942           }
 943         }
 944       }
 945     }
 946     return $this->assertTrue($fields && $found, $message, $group);
 947   }
 948
 949   /**
 950    * Asserts that a field exists in the current page by the given XPath.
 951    *
 952    * @param string $xpath
 953    *   XPath used to find the field.
 954    * @param string $value
 955    *   (optional) Value of the field to assert. You may pass in NULL (default)
 956    *   to skip checking the actual value, while still checking that the field
 957    *   exists.
 958    * @param string $message
 959    *   (optional) A message to display with the assertion. Do not translate
 960    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
 961    *   variables in the message text, not t(). If left blank, a default message
 962    *   will be displayed.
 963    * @param string $group
 964    *   (optional) The group this message is in, which is displayed in a column
 965    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
 966    *   translate this string. Defaults to 'Other'; most tests do not override
 967    *   this default.
 968    *
 969    * @return bool
 970    *   TRUE on pass, FALSE on fail.
 971    */
 972   protected function assertFieldByXPath($xpath, $value = NULL, $message = '', $group = 'Other') {
 973     $fields = $this->xpath($xpath);
 974
 975     return $this->assertFieldsByValue($fields, $value, $message, $group);
 976   }
 977
 978   /**
 979    * Get the selected value from a select field.
 980    *
 981    * @param \SimpleXmlElement $element
 982    *   SimpleXMLElement select element.
 983    *
 984    * @return bool
 985    *   The selected value or FALSE.
 986    */
 987   protected function getSelectedItem(\SimpleXMLElement $element) {
 988     foreach ($element->children() as $item) {
 989       if (isset($item['selected'])) {
 990         return $item['value'];
 991       }
 992       elseif ($item->getName() == 'optgroup') {
 993         if ($value = $this->getSelectedItem($item)) {
 994           return $value;
 995         }
 996       }
 997     }
 998     return FALSE;
 999   }
1000
1001   /**
1002    * Asserts that a field does not exist or its value does not match, by XPath.
1003    *
1004    * @param string $xpath
1005    *   XPath used to find the field.
1006    * @param string $value
1007    *   (optional) Value of the field, to assert that the field's value on the
1008    *   page does not match it.
1009    * @param string $message
1010    *   (optional) A message to display with the assertion. Do not translate
1011    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1012    *   variables in the message text, not t(). If left blank, a default message
1013    *   will be displayed.
1014    * @param string $group
1015    *   (optional) The group this message is in, which is displayed in a column
1016    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1017    *   translate this string. Defaults to 'Other'; most tests do not override
1018    *   this default.
1019    *
1020    * @return bool
1021    *   TRUE on pass, FALSE on fail.
1022    */
1023   protected function assertNoFieldByXPath($xpath, $value = NULL, $message = '', $group = 'Other') {
1024     $fields = $this->xpath($xpath);
1025
1026     // If value specified then check array for match.
1027     $found = TRUE;
1028     if (isset($value)) {
1029       $found = FALSE;
1030       if ($fields) {
1031         foreach ($fields as $field) {
1032           if ($field['value'] == $value) {
1033             $found = TRUE;
1034           }
1035         }
1036       }
1037     }
1038     return $this->assertFalse($fields && $found, $message, $group);
1039   }
1040
1041   /**
1042    * Asserts that a field exists with the given name and value.
1043    *
1044    * @param string $name
1045    *   Name of field to assert.
1046    * @param string $value
1047    *   (optional) Value of the field to assert. You may pass in NULL (default)
1048    *   to skip checking the actual value, while still checking that the field
1049    *   exists.
1050    * @param string $message
1051    *   (optional) A message to display with the assertion. Do not translate
1052    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1053    *   variables in the message text, not t(). If left blank, a default message
1054    *   will be displayed.
1055    * @param string $group
1056    *   (optional) The group this message is in, which is displayed in a column
1057    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1058    *   translate this string. Defaults to 'Browser'; most tests do not override
1059    *   this default.
1060    *
1061    * @return bool
1062    *   TRUE on pass, FALSE on fail.
1063    */
1064   protected function assertFieldByName($name, $value = NULL, $message = NULL, $group = 'Browser') {
1065     if (!isset($message)) {
1066       if (!isset($value)) {
1067         $message = SafeMarkup::format('Found field with name @name', [
1068           '@name' => var_export($name, TRUE),
1069         ]);
1070       }
1071       else {
1072         $message = SafeMarkup::format('Found field with name @name and value @value', [
1073           '@name' => var_export($name, TRUE),
1074           '@value' => var_export($value, TRUE),
1075         ]);
1076       }
1077     }
1078     return $this->assertFieldByXPath($this->constructFieldXpath('name', $name), $value, $message, $group);
1079   }
1080
1081   /**
1082    * Asserts that a field does not exist with the given name and value.
1083    *
1084    * @param string $name
1085    *   Name of field to assert.
1086    * @param string $value
1087    *   (optional) Value for the field, to assert that the field's value on the
1088    *   page doesn't match it. You may pass in NULL to skip checking the
1089    *   value, while still checking that the field doesn't exist. However, the
1090    *   default value ('') asserts that the field value is not an empty string.
1091    * @param string $message
1092    *   (optional) A message to display with the assertion. Do not translate
1093    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1094    *   variables in the message text, not t(). If left blank, a default message
1095    *   will be displayed.
1096    * @param string $group
1097    *   (optional) The group this message is in, which is displayed in a column
1098    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1099    *   translate this string. Defaults to 'Browser'; most tests do not override
1100    *   this default.
1101    *
1102    * @return bool
1103    *   TRUE on pass, FALSE on fail.
1104    */
1105   protected function assertNoFieldByName($name, $value = '', $message = '', $group = 'Browser') {
1106     return $this->assertNoFieldByXPath($this->constructFieldXpath('name', $name), $value, $message ? $message : SafeMarkup::format('Did not find field by name @name', ['@name' => $name]), $group);
1107   }
1108
1109   /**
1110    * Asserts that a field exists with the given ID and value.
1111    *
1112    * @param string $id
1113    *   ID of field to assert.
1114    * @param string|\Drupal\Component\Render\MarkupInterface $value
1115    *   (optional) Value for the field to assert. You may pass in NULL to skip
1116    *   checking the value, while still checking that the field exists.
1117    *   However, the default value ('') asserts that the field value is an empty
1118    *   string.
1119    * @param string|\Drupal\Component\Render\MarkupInterface $message
1120    *   (optional) A message to display with the assertion. Do not translate
1121    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1122    *   variables in the message text, not t(). If left blank, a default message
1123    *   will be displayed.
1124    * @param string $group
1125    *   (optional) The group this message is in, which is displayed in a column
1126    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1127    *   translate this string. Defaults to 'Browser'; most tests do not override
1128    *   this default.
1129    *
1130    * @return bool
1131    *   TRUE on pass, FALSE on fail.
1132    */
1133   protected function assertFieldById($id, $value = '', $message = '', $group = 'Browser') {
1134     // Cast MarkupInterface objects to string.
1135     if (isset($value)) {
1136       $value = (string) $value;
1137     }
1138     $message = (string) $message;
1139     return $this->assertFieldByXPath($this->constructFieldXpath('id', $id), $value, $message ? $message : SafeMarkup::format('Found field by id @id', ['@id' => $id]), $group);
1140   }
1141
1142   /**
1143    * Asserts that a field does not exist with the given ID and value.
1144    *
1145    * @param string $id
1146    *   ID of field to assert.
1147    * @param string $value
1148    *   (optional) Value for the field, to assert that the field's value on the
1149    *   page doesn't match it. You may pass in NULL to skip checking the value,
1150    *   while still checking that the field doesn't exist. However, the default
1151    *   value ('') asserts that the field value is not an empty string.
1152    * @param string $message
1153    *   (optional) A message to display with the assertion. Do not translate
1154    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1155    *   variables in the message text, not t(). If left blank, a default message
1156    *   will be displayed.
1157    * @param string $group
1158    *   (optional) The group this message is in, which is displayed in a column
1159    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1160    *   translate this string. Defaults to 'Browser'; most tests do not override
1161    *   this default.
1162    *
1163    * @return bool
1164    *   TRUE on pass, FALSE on fail.
1165    */
1166   protected function assertNoFieldById($id, $value = '', $message = '', $group = 'Browser') {
1167     return $this->assertNoFieldByXPath($this->constructFieldXpath('id', $id), $value, $message ? $message : SafeMarkup::format('Did not find field by id @id', ['@id' => $id]), $group);
1168   }
1169
1170   /**
1171    * Asserts that a checkbox field in the current page is checked.
1172    *
1173    * @param string $id
1174    *   ID of field to assert.
1175    * @param string $message
1176    *   (optional) A message to display with the assertion. Do not translate
1177    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1178    *   variables in the message text, not t(). If left blank, a default message
1179    *   will be displayed.
1180    * @param string $group
1181    *   (optional) The group this message is in, which is displayed in a column
1182    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1183    *   translate this string. Defaults to 'Browser'; most tests do not override
1184    *   this default.
1185    *
1186    * @return bool
1187    *   TRUE on pass, FALSE on fail.
1188    */
1189   protected function assertFieldChecked($id, $message = '', $group = 'Browser') {
1190     $elements = $this->xpath('//input[@id=:id]', [':id' => $id]);
1191     return $this->assertTrue(isset($elements[0]) && !empty($elements[0]['checked']), $message ? $message : SafeMarkup::format('Checkbox field @id is checked.', ['@id' => $id]), $group);
1192   }
1193
1194   /**
1195    * Asserts that a checkbox field in the current page is not checked.
1196    *
1197    * @param string $id
1198    *   ID of field to assert.
1199    * @param string $message
1200    *   (optional) A message to display with the assertion. Do not translate
1201    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1202    *   variables in the message text, not t(). If left blank, a default message
1203    *   will be displayed.
1204    * @param string $group
1205    *   (optional) The group this message is in, which is displayed in a column
1206    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1207    *   translate this string. Defaults to 'Browser'; most tests do not override
1208    *   this default.
1209    *
1210    * @return bool
1211    *   TRUE on pass, FALSE on fail.
1212    */
1213   protected function assertNoFieldChecked($id, $message = '', $group = 'Browser') {
1214     $elements = $this->xpath('//input[@id=:id]', [':id' => $id]);
1215     return $this->assertTrue(isset($elements[0]) && empty($elements[0]['checked']), $message ? $message : SafeMarkup::format('Checkbox field @id is not checked.', ['@id' => $id]), $group);
1216   }
1217
1218   /**
1219    * Asserts that a select option in the current page exists.
1220    *
1221    * @param string $id
1222    *   ID of select field to assert.
1223    * @param string $option
1224    *   Option to assert.
1225    * @param string $message
1226    *   (optional) A message to display with the assertion. Do not translate
1227    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1228    *   variables in the message text, not t(). If left blank, a default message
1229    *   will be displayed.
1230    * @param string $group
1231    *   (optional) The group this message is in, which is displayed in a column
1232    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1233    *   translate this string. Defaults to 'Browser'; most tests do not override
1234    *   this default.
1235    *
1236    * @return bool
1237    *   TRUE on pass, FALSE on fail.
1238    */
1239   protected function assertOption($id, $option, $message = '', $group = 'Browser') {
1240     $options = $this->xpath('//select[@id=:id]//option[@value=:option]', [':id' => $id, ':option' => $option]);
1241     return $this->assertTrue(isset($options[0]), $message ? $message : SafeMarkup::format('Option @option for field @id exists.', ['@option' => $option, '@id' => $id]), $group);
1242   }
1243
1244   /**
1245    * Asserts that a select option with the visible text exists.
1246    *
1247    * @param string $id
1248    *   The ID of the select field to assert.
1249    * @param string $text
1250    *   The text for the option tag to assert.
1251    * @param string $message
1252    *   (optional) A message to display with the assertion.
1253    *
1254    * @return bool
1255    *   TRUE on pass, FALSE on fail.
1256    */
1257   protected function assertOptionByText($id, $text, $message = '') {
1258     $options = $this->xpath('//select[@id=:id]//option[normalize-space(text())=:text]', [':id' => $id, ':text' => $text]);
1259     return $this->assertTrue(isset($options[0]), $message ?: 'Option with text label ' . $text . ' for select field ' . $id . ' exits.');
1260   }
1261
1262   /**
1263    * Asserts that a select option in the current page exists.
1264    *
1265    * @param string $drupal_selector
1266    *   The data drupal selector of select field to assert.
1267    * @param string $option
1268    *   Option to assert.
1269    * @param string $message
1270    *   (optional) A message to display with the assertion. Do not translate
1271    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1272    *   variables in the message text, not t(). If left blank, a default message
1273    *   will be displayed.
1274    * @param string $group
1275    *   (optional) The group this message is in, which is displayed in a column
1276    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1277    *   translate this string. Defaults to 'Browser'; most tests do not override
1278    *   this default.
1279    *
1280    * @return bool
1281    *   TRUE on pass, FALSE on fail.
1282    */
1283   protected function assertOptionWithDrupalSelector($drupal_selector, $option, $message = '', $group = 'Browser') {
1284     $options = $this->xpath('//select[@data-drupal-selector=:data_drupal_selector]//option[@value=:option]', [':data_drupal_selector' => $drupal_selector, ':option' => $option]);
1285     return $this->assertTrue(isset($options[0]), $message ? $message : SafeMarkup::format('Option @option for field @data_drupal_selector exists.', ['@option' => $option, '@data_drupal_selector' => $drupal_selector]), $group);
1286   }
1287
1288   /**
1289    * Asserts that a select option in the current page does not exist.
1290    *
1291    * @param string $id
1292    *   ID of select field to assert.
1293    * @param string $option
1294    *   Option to assert.
1295    * @param string $message
1296    *   (optional) A message to display with the assertion. Do not translate
1297    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1298    *   variables in the message text, not t(). If left blank, a default message
1299    *   will be displayed.
1300    * @param string $group
1301    *   (optional) The group this message is in, which is displayed in a column
1302    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1303    *   translate this string. Defaults to 'Browser'; most tests do not override
1304    *   this default.
1305    *
1306    * @return bool
1307    *   TRUE on pass, FALSE on fail.
1308    */
1309   protected function assertNoOption($id, $option, $message = '', $group = 'Browser') {
1310     $selects = $this->xpath('//select[@id=:id]', [':id' => $id]);
1311     $options = $this->xpath('//select[@id=:id]//option[@value=:option]', [':id' => $id, ':option' => $option]);
1312     return $this->assertTrue(isset($selects[0]) && !isset($options[0]), $message ? $message : SafeMarkup::format('Option @option for field @id does not exist.', ['@option' => $option, '@id' => $id]), $group);
1313   }
1314
1315   /**
1316    * Asserts that a select option in the current page is checked.
1317    *
1318    * @param string $id
1319    *   ID of select field to assert.
1320    * @param string $option
1321    *   Option to assert.
1322    * @param string $message
1323    *   (optional) A message to display with the assertion. Do not translate
1324    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1325    *   variables in the message text, not t(). If left blank, a default message
1326    *   will be displayed.
1327    * @param string $group
1328    *   (optional) The group this message is in, which is displayed in a column
1329    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1330    *   translate this string. Defaults to 'Browser'; most tests do not override
1331    *   this default.
1332    *
1333    * @return bool
1334    *   TRUE on pass, FALSE on fail.
1335    *
1336    * @todo $id is unusable. Replace with $name.
1337    */
1338   protected function assertOptionSelected($id, $option, $message = '', $group = 'Browser') {
1339     $elements = $this->xpath('//select[@id=:id]//option[@value=:option]', [':id' => $id, ':option' => $option]);
1340     return $this->assertTrue(isset($elements[0]) && !empty($elements[0]['selected']), $message ? $message : SafeMarkup::format('Option @option for field @id is selected.', ['@option' => $option, '@id' => $id]), $group);
1341   }
1342
1343   /**
1344    * Asserts that a select option in the current page is checked.
1345    *
1346    * @param string $drupal_selector
1347    *   The data drupal selector of select field to assert.
1348    * @param string $option
1349    *   Option to assert.
1350    * @param string $message
1351    *   (optional) A message to display with the assertion. Do not translate
1352    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1353    *   variables in the message text, not t(). If left blank, a default message
1354    *   will be displayed.
1355    * @param string $group
1356    *   (optional) The group this message is in, which is displayed in a column
1357    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1358    *   translate this string. Defaults to 'Browser'; most tests do not override
1359    *   this default.
1360    *
1361    * @return bool
1362    *   TRUE on pass, FALSE on fail.
1363    *
1364    * @todo $id is unusable. Replace with $name.
1365    */
1366   protected function assertOptionSelectedWithDrupalSelector($drupal_selector, $option, $message = '', $group = 'Browser') {
1367     $elements = $this->xpath('//select[@data-drupal-selector=:data_drupal_selector]//option[@value=:option]', [':data_drupal_selector' => $drupal_selector, ':option' => $option]);
1368     return $this->assertTrue(isset($elements[0]) && !empty($elements[0]['selected']), $message ? $message : SafeMarkup::format('Option @option for field @data_drupal_selector is selected.', ['@option' => $option, '@data_drupal_selector' => $drupal_selector]), $group);
1369   }
1370
1371   /**
1372    * Asserts that a select option in the current page is not checked.
1373    *
1374    * @param string $id
1375    *   ID of select field to assert.
1376    * @param string $option
1377    *   Option to assert.
1378    * @param string $message
1379    *   (optional) A message to display with the assertion. Do not translate
1380    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1381    *   variables in the message text, not t(). If left blank, a default message
1382    *   will be displayed.
1383    * @param string $group
1384    *   (optional) The group this message is in, which is displayed in a column
1385    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1386    *   translate this string. Defaults to 'Browser'; most tests do not override
1387    *   this default.
1388    *
1389    * @return bool
1390    *   TRUE on pass, FALSE on fail.
1391    */
1392   protected function assertNoOptionSelected($id, $option, $message = '', $group = 'Browser') {
1393     $elements = $this->xpath('//select[@id=:id]//option[@value=:option]', [':id' => $id, ':option' => $option]);
1394     return $this->assertTrue(isset($elements[0]) && empty($elements[0]['selected']), $message ? $message : SafeMarkup::format('Option @option for field @id is not selected.', ['@option' => $option, '@id' => $id]), $group);
1395   }
1396
1397   /**
1398    * Asserts that a field exists with the given name or ID.
1399    *
1400    * @param string $field
1401    *   Name or ID of field to assert.
1402    * @param string $message
1403    *   (optional) A message to display with the assertion. Do not translate
1404    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1405    *   variables in the message text, not t(). If left blank, a default message
1406    *   will be displayed.
1407    * @param string $group
1408    *   (optional) The group this message is in, which is displayed in a column
1409    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1410    *   translate this string. Defaults to 'Other'; most tests do not override
1411    *   this default.
1412    *
1413    * @return bool
1414    *   TRUE on pass, FALSE on fail.
1415    */
1416   protected function assertField($field, $message = '', $group = 'Other') {
1417     return $this->assertFieldByXPath($this->constructFieldXpath('name', $field) . '|' . $this->constructFieldXpath('id', $field), NULL, $message, $group);
1418   }
1419
1420   /**
1421    * Asserts that a field does not exist with the given name or ID.
1422    *
1423    * @param string $field
1424    *   Name or ID of field to assert.
1425    * @param string $message
1426    *   (optional) A message to display with the assertion. Do not translate
1427    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1428    *   variables in the message text, not t(). If left blank, a default message
1429    *   will be displayed.
1430    * @param string $group
1431    *   (optional) The group this message is in, which is displayed in a column
1432    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1433    *   translate this string. Defaults to 'Other'; most tests do not override
1434    *   this default.
1435    *
1436    * @return bool
1437    *   TRUE on pass, FALSE on fail.
1438    */
1439   protected function assertNoField($field, $message = '', $group = 'Other') {
1440     return $this->assertNoFieldByXPath($this->constructFieldXpath('name', $field) . '|' . $this->constructFieldXpath('id', $field), NULL, $message, $group);
1441   }
1442
1443   /**
1444    * Asserts that each HTML ID is used for just a single element.
1445    *
1446    * @param string $message
1447    *   (optional) A message to display with the assertion. Do not translate
1448    *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
1449    *   variables in the message text, not t(). If left blank, a default message
1450    *   will be displayed.
1451    * @param string $group
1452    *   (optional) The group this message is in, which is displayed in a column
1453    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
1454    *   translate this string. Defaults to 'Other'; most tests do not override
1455    *   this default.
1456    * @param array $ids_to_skip
1457    *   An optional array of ids to skip when checking for duplicates. It is
1458    *   always a bug to have duplicate HTML IDs, so this parameter is to enable
1459    *   incremental fixing of core code. Whenever a test passes this parameter,
1460    *   it should add a "todo" comment above the call to this function explaining
1461    *   the legacy bug that the test wishes to ignore and including a link to an
1462    *   issue that is working to fix that legacy bug.
1463    *
1464    * @return bool
1465    *   TRUE on pass, FALSE on fail.
1466    */
1467   protected function assertNoDuplicateIds($message = '', $group = 'Other', $ids_to_skip = []) {
1468     $status = TRUE;
1469     foreach ($this->xpath('//*[@id]') as $element) {
1470       $id = (string) $element['id'];
1471       if (isset($seen_ids[$id]) && !in_array($id, $ids_to_skip)) {
1472         $this->fail(SafeMarkup::format('The HTML ID %id is unique.', ['%id' => $id]), $group);
1473         $status = FALSE;
1474       }
1475       $seen_ids[$id] = TRUE;
1476     }
1477     return $this->assert($status, $message, $group);
1478   }
1479
1480   /**
1481    * Helper: Constructs an XPath for the given set of attributes and value.
1482    *
1483    * @param string $attribute
1484    *   Field attributes.
1485    * @param string $value
1486    *   Value of field.
1487    *
1488    * @return string
1489    *   XPath for specified values.
1490    */
1491   protected function constructFieldXpath($attribute, $value) {
1492     $xpath = '//textarea[@' . $attribute . '=:value]|//input[@' . $attribute . '=:value]|//select[@' . $attribute . '=:value]';
1493     return $this->buildXPathQuery($xpath, [':value' => $value]);
1494   }
1495
1496 }