Skip to content
Set of Hamcrest matchers for HTML assertrions
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

This is the set of Hamcrest matchers for HTML assertions

Build Status Scrutinizer Code Quality Code Coverage

Usage examples

Hamcrest allows you to create pretty complicated and flexible assertions. Just remember:

"You can" does not mean "you should".

The following example shows how we can ensure that there is an HTML form and password entered in it is not weak:

$html = '<div>
                <input name="password" value="strong password"/>

assertThat($html, is(htmlPiece(
                    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()


Information about general Hamcrest usage can be found at Hamcrest GitHub repository.

Available Matchers

  • htmlPiece() - checks that string is a valid HTML, parses it and passes control to given matcher if one present

    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()

    assertThat('<p></p>', htmlPiece(havingRootElement(withTagName('p'))));
  • havingDirectChild - checks given constraint against direct children

    assertThat('<p><b></b></p>', htmlPiece(havingRootElement(havingDirectChild(withTagName('b')))));
  • havingChild - checks given constraint against all children

    assertThat('<p><b></b></p>', htmlPiece(havingChild(withTagName('b'))));
  • withTagName - checks given constraint against tag name

    assertThat('<p><b></b></p>', htmlPiece(havingChild(withTagName(
  • withAttribute - checks given constraint against elements attributes comparing names and values

    assertThat('<p><input required></p>', htmlPiece(havingChild(withAttribute('required'))));
    assertThat('<p><input data-value="some data"></p>', htmlPiece(havingChild(
        withAttribute(startsWith('data-'))->havingValue('some data'))));
  • withClass - checks given constraint against element's class list

    assertThat('<p class="class1 class2 class3"></p>', htmlPiece(havingChild(
  • havingTextContents - checks given constraint against elements text contents

    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)\

    That means:

    • 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:

    assertThat('<form><input id="id-pass" name="password" class="pretty green" required="required"></form>', 
            tagMatchingOutline('<input name="password" class="green" required>')
You can’t perform that action at this time.