Merge 4e1e5b9 into f9f5a69

documentation/assertions/DOMElement/to-contain.md

@@ -0,0 +1,89 @@
+Assert that an element contains descendant elements satisfying a given specification.
+
+```js
+var element = createElement(`
+  <section>
+    <h1 class='title' data-test-id='title'>Assert on text content</h1>
+    <p>
+      Learn about howto assert on the text content of a DOM element.
+    </p>
+    <p data-test-id='learn'>
+      Learn more <a href='https://example.com/learn'>here</a>.
+    </p>
+  </section>
+`);
+```
+
+Expect that an element contains a subtree satisfying a HTML fragment given as
+string:
+
+```js
+expect(element, 'to contain', '<h1>Assert on text content</h1>');
+```
+
+You can also assert against a DOM element:
+
+```js
+expect(element, 'to contain', createElement('<h1>Assert on text content</h1>'));
+```
+
+Finally you can also use the full power of [to
+satisfy](http://unexpected.js.org/assertions/any/to-satisfy/) where you provide
+the subtree you expect the subject to contain:
+
+```js
+expect(element, 'to contain', {
+  children: [
+    /^Learn/,
+    {
+      name: 'a',
+      attributes: {
+        href: 'https://example.com/learn'
+      },
+      children: ['here']
+    },
+    '.'
+  ]
+});
+```
+
+When the assertion fails you get a nice descriptive error:
+
+```js
+expect(element, 'to contain', '<h1 class="heading">Assert on all content</h1>');
+```
+
+```output
+expected
+<section>
+  <h1 class="title" data-test-id="title">
+    Assert on text content
+  </h1>
+  <p>
+    Learn about howto assert on the text content of a DOM element.
+  </p>
+  <p data-test-id="learn">
+    Learn more
+    <a href="https://example.com/learn">...</a>
+    .
+  </p>
+</section>
+to contain <h1 class="heading">Assert on all content</h1>
+
+<h1
+  class="title" // expected [ 'title' ] to contain 'heading'
+  data-test-id="title"
+>
+  Assert on text content // should equal 'Assert on all content'
+                         //
+                         // -Assert on text content
+                         // +Assert on all content
+</h1>
+```
+
+You can also assert that the element has no descendant elements satisfying the
+given specification:
+
+```js
+expect(element, 'not to contain', '<h1 class="heading">Assert on all content</h1>');
+```

documentation/assertions/DOMNodeList/to-contain.md

@@ -0,0 +1,69 @@
+Assert that a DOM node list contains elements satisfying a given specification.
+
+See [to contain](../../DOMElement/to-contain/) for more details.
+
+```js
+var element = createElement(`
+  <section>
+    <h1>Numbers</h1>
+    <hr>
+    <ol data-test-id="numbers">
+      <li class="number">One</li>
+      <li class="number">Two</li>
+      <li class="number">Three</li>
+    </ol>
+  </section>
+`);
+
+expect(element, 'queried for', 'li', 'to contain', '<li>One</li>');
+
+expect(element, 'to contain', { textContent: 'Three' });
+
+expect(element, 'to contain', { name: 'li', textContent: /One|Two|Tree/ });
+```
+
+In case of a failing expectation you get the following output:
+
+```js
+expect(
+  element,
+  'queried for',
+  'li',
+  'to contain',
+  '<li class="count">Three</li>'
+);
+```
+
+```output
+expected
+<section><h1>Numbers</h1><hr><ol data-test-id="numbers">
+  <li class="number">...</li>
+  <li class="number">...</li>
+  <li class="number">...</li>
+</ol></section>
+queried for li to contain '<li class="count">Three</li>'
+  expected
+  NodeList[
+    <li class="number">One</li>,
+    <li class="number">Two</li>,
+    <li class="number">Three</li>
+  ]
+  to contain <li class="count">Three</li>
+
+  <li
+    class="number" // expected [ 'number' ] to contain 'count'
+  >Three</li>
+```
+
+You can also assert that the element has no descendant elements satisfying the
+given specification:
+
+```js
+expect(
+  element,
+  'queried for',
+  'li',
+  'not to contain',
+  '<li class="count">Three</li>'
+);
+```