First class support for test id's

documentation/assertions/DOMElement/queried-for-test-id.md

@@ -0,0 +1,78 @@
+Queries the subject element for the first descendant element with the given `data-test-id`
+attribute and forwards it to another assertion.
+
+If the data-test-id is not found it fails.
+
+```js
+var element = createElement(`
+  <section>
+    <h1>Numbers</h1>
+    <hr>
+    <ol data-test-id="numbers">
+      <li >One</li>
+      <li>Two</li>
+      <li>Three</li>
+    </ol>
+  </section>
+`);
+
+expect(element, 'queried for test id', 'numbers', 'to satisfy', {
+  children: expect.it('to have length', 3)
+});
+```
+
+If no matching element can be found you get the following error:
+
+```js
+expect(element, 'queried for test id', 'emojies', 'to satisfy', {
+  children: expect.it('to have length', 666)
+});
+```
+
+```output
+expected
+<section>
+  <h1>Numbers</h1>
+  <hr>
+  <ol data-test-id="numbers">
+    <li>...</li>
+    <li>...</li>
+    <li>...</li>
+  </ol>
+</section>
+queried for test id 'emojies' to satisfy { children: expect.it('to have length', 666) }
+  expected DOMElement queried for first [data-test-id="emojies"]
+    The selector [data-test-id="emojies"] yielded no results
+```
+
+In case the next assertion fails you will get an error looking like this:
+
+```js
+expect(
+  element,
+  'queried for test id',
+  'numbers',
+  'to have no children'
+);
+```
+
+```output
+expected
+<section>
+  <h1>Numbers</h1>
+  <hr>
+  <ol data-test-id="numbers">
+    <li>...</li>
+    <li>...</li>
+    <li>...</li>
+  </ol>
+</section>
+queried for test id 'numbers' to have no children
+  expected
+  <ol data-test-id="numbers">
+    <li>One</li>
+    <li>Two</li>
+    <li>Three</li>
+  </ol>
+  to have no children
+```

documentation/assertions/DOMElement/queried-for.md

@@ -1,6 +1,6 @@
 Queries the subject element with the given CSS selector and forwards it to another assertion.
 
-If the selector doesn't match anything is fails.
+If the selector doesn't match anything it fails.
 
 ```js
 var element = createElement(`

documentation/assertions/DOMElement/to-contain-elements-matching.md

@@ -36,17 +36,17 @@ expected
 to contain elements matching '[data-test-id=emojies]'
 ```
 
-Using the `no` flag, you can assert that the selector can't matching any
+Using the `not` flag, you can assert that the selector can't matching any
 descendant elements:
 
 ```js
-expect(element, 'to contain no elements matching', '[data-test-id=emojies]');
+expect(element, 'not to contain elements matching', '[data-test-id=emojies]');
 ```
 
 You get the following error when it fails:
 
 ```js
-expect(element, 'to contain no elements matching', 'li');
+expect(element, 'not to contain elements matching', 'li');
 ```
 
 ```output
@@ -60,7 +60,7 @@ expected
     <li>...</li>
   </ol>
 </section>
-to contain no elements matching 'li'
+not to contain elements matching 'li'
 
 NodeList[
   <li>One</li>, // should be removed

documentation/assertions/DOMElement/to-contain-test-id.md

@@ -0,0 +1,75 @@
+Assert that an element contains a descendant element with element with the given `data-test-id`
+attribute.
+
+```js
+var element = createElement(`
+  <section>
+    <h1>Numbers</h1>
+    <hr>
+    <ol data-test-id="numbers">
+      <li>One</li>
+      <li>Two</li>
+      <li>Three</li>
+    </ol>
+  </section>
+`);
+
+expect(element, 'to contain test id', 'numbers');
+```
+
+You get the following error when it fails:
+
+```js
+expect(element, 'to contain test id', 'emojies');
+```
+
+```output
+expected
+<section>
+  <h1>Numbers</h1>
+  <hr>
+  <ol data-test-id="numbers">
+    <li>...</li>
+    <li>...</li>
+    <li>...</li>
+  </ol>
+</section>
+to contain test id 'emojies'
+  expected DOMElement to contain elements matching '[data-test-id="emojies"]'
+```
+
+Using the `not` flag, you can assert that the test id shouldn't be found on any
+descendant elements:
+
+```js
+expect(element, 'not to contain test id', 'emojies');
+```
+
+You get the following error when it fails:
+
+```js
+expect(element, 'not to contain test id', 'numbers');
+```
+
+```output
+expected
+<section>
+  <h1>Numbers</h1>
+  <hr>
+  <ol data-test-id="numbers">
+    <li>...</li>
+    <li>...</li>
+    <li>...</li>
+  </ol>
+</section>
+not to contain test id 'numbers'
+  expected DOMElement not to contain elements matching '[data-test-id="numbers"]'
+
+  NodeList[
+    <ol data-test-id="numbers">
+      <li>...</li>
+      <li>...</li>
+      <li>...</li>
+    </ol> // should be removed
+  ]
+```

documentation/assertions/DOMElement/to-have-test-id.md

@@ -0,0 +1,47 @@
+Assert that an element have the given `data-test-id` attribute.
+
+```js
+var element = createElement(`
+  <button data-test-id="publish" class="primary" disabled>
+    Publish
+  </button>
+`);
+
+expect(element, 'to have test id', 'publish');
+```
+
+In case of a failing expectation you get the following output:
+
+```js
+expect(element, 'to have test id', 'approve');
+```
+
+```output
+expected
+<button data-test-id="publish" class="primary" disabled>
+  Publish
+</button>
+to have test id 'approve'
+  expected DOMElement to match '[data-test-id="approve"]'
+```
+
+You can also assert that an element does not have a test id:
+
+```js
+expect(element, 'not to have test id', 'approve');
+```
+
+In case of a failing expectation you get the following output:
+
+```js
+expect(element, 'not to have test id', 'publish');
+```
+
+```output
+expected
+<button data-test-id="publish" class="primary" disabled>
+  Publish
+</button>
+not to have test id 'publish'
+  expected DOMElement not to match '[data-test-id="publish"]'
+```

src/index.js

@@ -1426,9 +1426,27 @@ module.exports = {
     );
 
     expect.exportAssertion(
-      '<DOMDocument|DOMElement|DOMDocumentFragment> to contain [no] elements matching <string>',
+      '<DOMDocument|DOMElement|DOMDocumentFragment> [when] queried for test id <string> <assertion?>',
+      (expect, subject, testId) => {
+        expect.errorMode = 'nested';
+
+        const escapedTestId = JSON.stringify(testId);
+
+        return expect(
+          subject,
+          'queried for first',
+          `[data-test-id=${escapedTestId}]`
+        ).then(queryResult => expect.shift(queryResult));
+      }
+    );
+
+    expect.exportAssertion(
+      [
+        '<DOMDocument|DOMElement|DOMDocumentFragment> to contain [no] elements matching <string>',
+        '<DOMDocument|DOMElement|DOMDocumentFragment> [not] to contain elements matching <string>'
+      ],
       (expect, subject, query) => {
-        if (expect.flags.no) {
+        if (expect.flags.no || expect.flags.not) {
           return expect(subject.querySelectorAll(query), 'to satisfy', []);
         }
 
@@ -1439,6 +1457,21 @@ module.exports = {
       }
     );
 
+    expect.exportAssertion(
+      '<DOMDocument|DOMElement|DOMDocumentFragment> [not] to contain test id <string>',
+      (expect, subject, testId) => {
+        expect.errorMode = 'nested';
+
+        const escapedTestId = JSON.stringify(testId);
+
+        return expect(
+          subject,
+          '[not] to contain elements matching',
+          `[data-test-id=${escapedTestId}]`
+        );
+      }
+    );
+
     expect.exportAssertion(
       '<DOMDocument|DOMElement|DOMDocumentFragment> [not] to match <string>',
       (expect, subject, query) => {
@@ -1449,6 +1482,23 @@ module.exports = {
       }
     );
 
+    expect.exportAssertion(
+      '<DOMDocument|DOMElement|DOMDocumentFragment> [not] to have test id <string>',
+      (expect, subject, testId) => {
+        expect.errorMode = 'nested';
+        expect.subjectOutput = output =>
+          expect.inspect(subject, Infinity, output);
+
+        const escapedTestId = JSON.stringify(testId);
+
+        return expect(
+          subject,
+          '[not] to match',
+          `[data-test-id=${escapedTestId}]`
+        );
+      }
+    );
+
     expect.exportAssertion(
       '<string> [when] parsed as (html|HTML) [fragment] <assertion?>',
       (expect, subject) => {