Merge pull request #30 from veewee/dom-assert

Add assertion methods

docs/dom.md

@@ -41,6 +41,7 @@ $count = $xpath->evaluate('count(.//item)', Type\int(), $currentNode);
 Of course, the example above only gives you a small idea of all the implemented features.
 Let's find out more by segregating the DOM component into its composable blocks:
 
+* [Assertions](#assertions): Assert if a DOMNode is of a specific type.
 * [Builders](#builders): Let you build XML by using a declarative API.
 * [Collection](#collection): A wrapper for dealing with lists of nodes.
 * [Configurators](#configurators): Specify how you want to configure your DOM document.
@@ -54,6 +55,47 @@ Let's find out more by segregating the DOM component into its composable blocks:
 * [XPath](#xpath): Query for specific elements based on XPath queries.
 
 
+## Assertions
+
+Assert if a DOMNode is of a specific type.
+
+#### assert_document
+
+Assert if a node is of type `DOMDocument`.
+
+```php
+use Psl\Type\Exception\AssertException;
+use function VeeWee\Xml\Dom\Assert\assert_document;
+
+try {
+    assert_document($someNode)
+} catch (AssertException $e) {
+    // Deal with it
+}
+```
+
+#### assert_element
+
+Assert if a node is of type `DOMElement`.
+
+```php
+use Psl\Type\Exception\AssertException;
+use VeeWee\XML\DOM\Document;
+use function VeeWee\Xml\Dom\Assert\assert_element;
+
+$doc = Document::fromXmlFile('some.xml');
+$item = $doc->xpath()->query('item')->item(0);
+
+use Psl\Type\Exception\AssertException;
+use function VeeWee\Xml\Dom\Assert\assert_document;
+
+try {
+    assert_element($someNode)
+} catch (AssertException $e) {
+    // Deal with it
+}
+```
+
 ## Builders
 
 Lets you build XML by using a declarative API.

src/Xml/Dom/Assert/assert_document.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Xml\Dom\Assert;
+
+use DOMDocument;
+use DOMNode;
+use Psl\Type\Exception\AssertException;
+use function Psl\Type\object;
+
+/**
+ * @psalm-assert DOMDocument $node
+ * @throws AssertException
+ */
+function assert_document(?DOMNode $node): DOMDocument
+{
+    return object(DOMDocument::class)->assert($node);
+}

src/Xml/Dom/Assert/assert_element.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Xml\Dom\Assert;
+
+use DOMElement;
+use DOMNode;
+use Psl\Type\Exception\AssertException;
+use function Psl\Type\object;
+
+/**
+ * @psalm-assert DOMElement $node
+ * @throws AssertException
+ */
+function assert_element(?DOMNode $node): DOMElement
+{
+    return object(DOMElement::class)->assert($node);
+}

src/bootstrap.php

@@ -1,5 +1,7 @@
 <?php declare(strict_types=1);
 
+require_once __DIR__.'/Xml/Dom/Assert/assert_document.php';
+require_once __DIR__.'/Xml/Dom/Assert/assert_element.php';
 require_once __DIR__.'/Xml/Dom/Builder/attribute.php';
 require_once __DIR__.'/Xml/Dom/Builder/attributes.php';
 require_once __DIR__.'/Xml/Dom/Builder/children.php';

tests/Xml/Dom/Assert/AssertDocumentTest.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Tests\Xml\Dom\Assert;
+
+use DOMNode;
+use PHPUnit\Framework\TestCase;
+use Psl\Type\Exception\AssertException;
+use VeeWee\Xml\Dom\Document;
+use function VeeWee\Xml\Dom\Assert\assert_document;
+
+final class AssertDocumentTest extends TestCase
+{
+    /**
+     *
+     * @dataProvider provideTestCases
+     */
+    public function test_it_knows_documents(?DOMNode $node, bool $expected): void
+    {
+        if (!$expected) {
+            $this->expectException(AssertException::class);
+        }
+
+        $actual = assert_document($node);
+        static::assertSame($node, $actual);
+    }
+
+    public function provideTestCases()
+    {
+        $doc = Document::fromXmlString(
+            <<<EOXML
+            <doc>
+                <item attr="val">Hello</item>
+            </doc>
+            EOXML
+        )->toUnsafeDocument();
+
+        yield [$doc, true];
+        yield [$doc->documentElement, false];
+        yield [$doc->documentElement->firstElementChild, false];
+        yield [$doc->documentElement->firstElementChild->attributes->getNamedItem('attr'), false];
+        yield [$doc->documentElement->firstElementChild->firstChild, false];
+        yield [null, false];
+    }
+}

tests/Xml/Dom/Assert/AssertElementTest.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Tests\Xml\Dom\Assert;
+
+use DOMNode;
+use PHPUnit\Framework\TestCase;
+use Psl\Type\Exception\AssertException;
+use VeeWee\Xml\Dom\Document;
+use function VeeWee\Xml\Dom\Assert\assert_element;
+
+final class AssertElementTest extends TestCase
+{
+    /**
+     *
+     * @dataProvider provideTestCases
+     */
+    public function test_it_knows_elements(?DOMNode $node, bool $expected): void
+    {
+        if (!$expected) {
+            $this->expectException(AssertException::class);
+        }
+
+        $actual = assert_element($node);
+        static::assertSame($node, $actual);
+    }
+
+    public function provideTestCases()
+    {
+        $doc = Document::fromXmlString(
+            <<<EOXML
+            <doc>
+                <item attr="val">Hello</item>
+            </doc>
+            EOXML
+        )->toUnsafeDocument();
+
+        yield [$doc, false];
+        yield [$doc->documentElement, true];
+        yield [$doc->documentElement->firstElementChild, true];
+        yield [$doc->documentElement->firstElementChild->attributes->getNamedItem('attr'), false];
+        yield [$doc->documentElement->firstElementChild->firstChild, false];
+        yield [null, false];
+    }
+}