wmde/hamcrest-html-matchers

Set of Hamcrest matchers for HTML assertions

This is the set of Hamcrest matchers for HTML assertions

, _(*1)

Usage examples

Hamcrest allows you to create pretty complicated and flexible assertions. Just remember:, _(*2)

"You can" does not mean "you should"., _(*3)

The following example shows how we can ensure that there is an HTML form and password entered in it is not weak:, _(*4)

$html = '


            

                
            
         

';

assertThat($html, is(htmlPiece(
    havingChild(
        both(withTagName('form'))
        ->andAlso(
            havingDirectChild(
                allOf(
                    withTagName('input'),
                    withAttribute('name')->havingValue('password'),
                    withAttribute('value')->havingValue(not('weak password')))))))));

Usage limitations: * Each HTML assertion starts with htmlPiece() call (is() can be used to improve readability) * One of havingRootElement(), havingDirectChild() or havingChild() needed to be passed as an argument to htmlPiece(), _(*5)

Documentation

Information about general Hamcrest usage can be found at Hamcrest GitHub repository., _(*6)

Available Matchers

• htmlPiece() - checks that string is a valid HTML, parses it and passes control to given matcher if one present php assertThat('<p></p>', is(htmlPiece())); // Just checking that string is a valid piece of HTML

• havingRootElement - checks given constraint against root element of HTML. NOTE: Can be passed only to htmlPiece(), _(*7)

  assertThat('<p></p>', htmlPiece(havingRootElement(withTagName('p'))));
  

• havingDirectChild - checks given constraint against direct children, _(*8)

  assertThat('<p><b></b></p>', htmlPiece(havingRootElement(havingDirectChild(withTagName('b')))));
  

• havingChild - checks given constraint against all children, _(*9)

  assertThat('<p><b></b></p>', htmlPiece(havingChild(withTagName('b'))));
  

• withTagName - checks given constraint against tag name, _(*10)

  assertThat('<p><b></b></p>', htmlPiece(havingChild(withTagName(
      either(equalTo('i'))->orElse(equalTo('b'))
  ))));
  

• withAttribute - checks given constraint against elements attributes comparing names and values, _(*11)

  assertThat('<p><input required></p>', htmlPiece(havingChild(withAttribute('required'))));
  

  php assertThat('<p><input data-value="some data"></p>', htmlPiece(havingChild( withAttribute(startsWith('data-'))->havingValue('some data'))));, _(*12)

• withClass - checks given constraint against element's class list, _(*13)

  assertThat('<p class="class1 class2 class3"></p>', htmlPiece(havingChild(
      withClass('class2'))));
  

• havingTextContents - checks given constraint against elements text contents, _(*14)

  assertThat('<div><p>this is Some Text</p></div>', htmlPiece(havingChild(
      havingTextContents(containsString('some text')->ignoringCase()))));
  

• tagMatchingOutline - tolerantly checks that tag matches given outline (outline - tag representation in HTML format), _(*15)

  That means:, _(*16)

  • Element's tag name is equal to outline's tag name
  • Element has all the attributes that outline has with the same values. If element has more attributes than outline it still matches.
    • NOTE: Attribute class is treated in a different manner (see further).
    • NOTE: If attribute outlined is boolean, then its value in element won't be checked, just presence.
  • Element has all html classes that outline has.

  This will pass:, _(*17)

  assertThat('<form><input id="id-pass" name="password" class="pretty green" required="required"></form>', 
    htmlPiece(havingChild(
        tagMatchingOutline('<input name="password" class="green" required>')
  )));