To Do List

[ziadoz]

[ziadoz]

Future:

Extend/Wrap the HtmlDocument and HtmlElement classes with assertables:

$assertables = AssertableHtmlDocument::createFromString(...)
    ->querySelectorAll('body :is(p, ul)');

$assertables[0]->assertTextEquals('Foo Bar'); // AssertableParagraphHtmlElement
$assertables[1]->assertTextEquals('Foo Bar Baz'); // AssertableUnorderedListHtmlElement

This would be a bit tricky, as each class is final, so I'd need to actually mimic them and their properties class by class, including NodeList and TokenList. Would also need to disable any DOM modifying or manipulation methods. The class methods also aren't currently documented (PhpStorm has stubs though).

It would be way nicer though, as we'd just be augmenting the default API. Might be worth prototyping.

Prototype Code

class AssertableHtmlDocument
{
    public function __construct(private \Dom\HTMLDocument|\Dom\Document|null $document = null)
    {
        $this->document ??= \Dom\HTMLDocument::createEmpty();
    }

    public static function createEmpty(string $encoding = "UTF-8"): static
    {
        return new static(\Dom\HTMLDocument::createEmpty(...func_get_args()));
    }

    public static function createFromFile(string $path, int $options = 0, ?string $overrideEncoding = null): static
    {
        return new static(\Dom\HTMLDocument::createFromFile(...func_get_args()));
    }

    public static function createFromString(string $source, int $options = 0, ?string $overrideEncoding = null): static
    {
        return new static(\Dom\HTMLDocument::createFromString(...func_get_args()));
    }

    public function saveHtml(?Node $node = null): string
    {
        return $this->document->saveHtml(...func_get_args());
    }

    public function saveHtmlFile(string $filename): int|false
    {
        return $this->document->saveHtmlFile(...func_get_args());
    }

    public function debugGetTemplateCount(): int
    {
        return $this->document->debugGetTemplateCount();
    }

    public function querySelector(string $selectors): ?AssertableHtmlElement
    {
        return ($element = $this->document->querySelector(...func_get_args())) !== null
            ? new AssertableHtmlElement($element)
            : null;
    }

    public function querySelectorAll(string $selectors): AssertableHtmlNodeList
    {
        return new AssertableHtmlNodeList($this->document->querySelectorAll(...func_get_args()));
    }

    //public function getElementsByTagName(string $qualifiedName): HTMLCollection {}
    //public function getElementById(string $elementId): ?Element {}
}

class AssertableHtmlElement
{
    public string $tagName;

    public function __construct(private \Dom\HTMLElement|\Dom\Element $element)
    {
        $this->tagName = $this->element->tagName;
    }

    public function assertTextEquals(string $text): static
    {
        assert($this->element->textContent === $text);

        return $this;
    }
}

class AssertableHtmlNodeList implements \ArrayAccess, \Countable, \IteratorAggregate
{
    public int $length = 0;

    public function __construct(private \Dom\NodeList $nodes)
    {
        $this->length = $this->nodes->length;
    }

    public function count(): int
    {
        return $this->nodes->count();
    }

    public function getIterator(): \Traversable
    {
        foreach ($this->nodes as $node) {
            yield new AssertableHtmlElement($node);
        }
    }

    public function item(int $index): ?AssertableHtmlElement
    {
        return ($element = $this->nodes->item($index)) !== null
            ? new AssertableHtmlElement($element)
            : null;
    }

    public function offsetExists(mixed $offset): bool
    {
        return isset($this->nodes[$offset]);
    }

    public function offsetGet(mixed $offset): AssertableHtmlElement
    {
        return new AssertableHtmlElement($this->nodes[$offset]);
    }

    public function offsetSet(mixed $offset, mixed $value): void
    {
        throw new RuntimeException('Unable to add element');
    }

    public function offsetUnset(mixed $offset): void
    {
        throw new RuntimeException('Unable to remove element');
    }
}

$assertable = AssertableHtmlDocument::createFromString(<<<HTML
    <p>I am a paragraph.</p>
    <ul><li>Foo</li><li>Bar</li></ul>
HTML, LIBXML_NOERROR);

$p = $assertable->querySelector('p');
$p->assertTextEquals('I am a paragraph.');

$pAndUl = $assertable->querySelectorAll(':is(p, ul)');
$pAndUl[1]->assertTextEquals('FooBar');

dump($p, $pAndUl);
dump(collect($pAndUl)->map(fn ($el) => $el->tagName));

Instead of trying to extend the HtmlDocument/Element classes, it would be simpler to just write an API that mimics them instead. It would be possible for someone to modify the DOM still potentially, but that would be their problem.

Classes:

• AssertableHtmlDocument - Mimics HtmlDocument (qs, qsa, tag name, id methods only).
• AssertableHtmlElement - Mimics HtmlElement with assertions
• AssertableHtmlElementsList - Mimics NodeList with some extra bits and bobs
• AssertableHtml(Form|Input|Select|...)Element - Extends AssertableHtmlElement with element-specific assertions
• AssertableHtmlElementMatcher - Matches an AssertableHtmlElement to it's custom class
• AssertClassList - Allows class value/contains/all/any to be asserted

AssertableHtmlElement:

• Could still have when(), with() and elsewhere() helper methods for scoping.
• Add a identifier() method which returns [p#id.foo.bar] type string.
• Add normaliseText()` method.
• Add getNormalisedAttribute() proxy methods.
• $classes and $attributes array properties.

Traits:

• AssertsElements
• AssertsElementsList

AssertableHtml:

• Use Lazy Proxy objects to handle firstChild, lastChild, parent etc. properties. So we only create an assertable HTML element when one is actually access rather than it triggering the entire chain.
• AssertableHtmlDocument::proxy() for ownerDocument.

AssertableHtmlElementsList:

• assertCount(), assertAll(), assertAny(), filter(), each(), nth() (3c78f4d#diff-1c905986eca40747766c8e97a541ddb05405a4ebff6a63594b4154ef9d2993f7L55)
• Drop index(), namedIndex() as we don't need to match HtmlCollection/NodeList
• __debugInfo()

Some kind of generic "everything" helper method:

$html->querySelector('input')->assertEl(text: '', attrs: [], classes: []);

Make all classes final except the element class so custom elements can extend it. Custom elements should have their own properties (e.g. $form->method, $form->uploads, form->action etc.).

Put examples in docblock and write a quick script to use in docs/ folder and README.

Strip out invisible characters: https://github.com/laravel/framework/pull/54281/files

---

Goals:

• The end result should be a similar but not identical API to the PHP 8.4 HTML5 API.
• Traversing the document should be very similar.
• It shouldn't be possible to modify or move any nodes or change any HTML.
• There shouldn't be any Attr or Text classes, or Node, ParentNode classes.
• The Assertable(Document|Element) should have similar properties to the element it wraps, but not identical.

[ziadoz]

• Finish readme documentation
• Add assertView() and assertComponent() to mixins, update assertElement() to require selector
• Consider renaming scope() to using() and add it to document
• Consider renaming with()/many()/elsewhere() to find()/findMany()/findElsewhere()
• Add CI for running tests and Pint
• Add to Packagist
• Quick assertions (post release)
• Finish custom elements and components feature (post release)
• Create 1.x branch and tag release v0.1.0

[ziadoz]

Custom Element Assertions:

• Assert things in order (e.g. table cells, list items).
• Assert parsed URL parts (e.g. href contains hostname, path, querystring etc.) - assertUriAttribute(), assertUriAttributeEquals().
• Could change assertMany() to some kind of higher order proxy.

Quick Assertions:

$el->assert()
   ->text('Hello, World')
   ->attrs(['id' => 'foo'])
   ->attr('data-bar', 'foo-bar')
   ->class(['foo', 'bar']);

// - text() accepts string or callable or null
// - attrs() accepts array or callable or null
// - attrs() accepts string or callable as 2nd param or null
// - class() accepts array or string(s) or null

// OR Pest style bare functions...

el()
    ->assert()
    ->text(...)
    ->attrs(...)
    ->attr(...)
    ->classes(...)
    ->class(...)
    ->not()
    ->text(...);

See: #7