Rename with() -> one() and scope() -> with() (#12)

* rename with() to one()

* rename trait to targetable

* pint

* rename scope() to with()

* rename trait

* pint

Author: ziadoz

README.md

@@ -179,7 +179,7 @@ public function testComponent: void
             ->assertAttributeEquals('method', 'post')
             ->assertAttributeEquals('action', '/foo/bar');
 
-        $form->with('input[name="name"]', function (AssertableElement $input) {
+        $form->one('input[name="name"]', function (AssertableElement $input) {
             $input->assertAttributeEquals('value', 'My New Action');
             $input->assertAttributePresent('required');
             $input->assertClassContains('form-input');
@@ -366,12 +366,12 @@ $document->getElementById('bar');
 
 ### Scopes
 
-Sometimes your assertions need room to breathe. For this you can use `with()`, `many()`, `elsewhere()` and `scope()` to filter elements into a callback for better readability.
+Sometimes your assertions need room to breathe. For this you can use `one()`, `many()`, `elsewhere()` and `with()` to filter elements into a callback for better readability.
 
-- `with()`: The first matching element in the **current** scope using `querySelector()`.
+- `one()`: The first matching element in the **current** scope using `querySelector()`.
 - `many()`: Every matching element in the **current** scope using `querySelectorAll()`,
 - `elsewhere()`: The first matching element in the **document** scope using `querySelector()`.
-- `scope()`: The current element.
+- `with()`: The current element.
 
 Let's give them a try:
 
@@ -392,7 +392,7 @@ $document = AssertableDocument::createFromString(<<<'HTML'
     </div>
 HTML, LIBXML_HTML_NOIMPLIED);
 
-$document->with('div#inner', function (AssertableElement $inner) {
+$document->one('div#inner', function (AssertableElement $inner) {
     $inner->assertIdEquals('inner');
 
     $inner->many('div.innermost', function (AssertableElementsList $innerMosts) {
@@ -403,7 +403,7 @@ $document->with('div#inner', function (AssertableElement $inner) {
         $anotherInner->assertIdEquals('another-inner');
     });
 
-    $inner->scope(function (AssertableElement $inner) {
+    $inner->with(function (AssertableElement $inner) {
         $inner->assertIdEquals('inner');
     });
 });
@@ -522,5 +522,5 @@ This package wouldn't be possible without the following people and projects:
 - Rachel ❤️, Archie 🐶 and Rigby 🐶
 - Niels Dossche (PHP 8.4 HTML parsing API author)
 - [Laravel DOM Assertions](https://github.com/sinnbeck/laravel-dom-assertions) for showing me the possibilities of HTML assertions
-- [Laravel Dusk](https://github.com/laravel/dusk) for showing me the `with()` and `elsewhere()` scoping syntax
+- [Laravel Dusk](https://github.com/laravel/dusk) for showing me the `one()` and `elsewhere()` scoping syntax
 - [Lexbor](https://github.com/lexbor/lexbor) (the library that powers PHP 8.4's HTML parsing API)

src/Concerns/Scopeable.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ziadoz\AssertableHtml\Concerns;
+
+use Ziadoz\AssertableHtml\Dom\AssertableDocument;
+use Ziadoz\AssertableHtml\Dom\AssertableElement;
+use Ziadoz\AssertableHtml\Dom\AssertableElementsList;
+
+trait Targetable
+{
+    /**
+     * Scope the first assertable element within the current assertable document or element matching the given selector.
+     *
+     * @param  callable(AssertableElement $assertable): void  $callback
+     */
+    public function one(string $selector, callable $callback): static
+    {
+        $callback($this->querySelector($selector));
+
+        return $this;
+    }
+
+    /**
+     * Scope the matching assertable elements within the current assertable document or element matching the given selector.
+     *
+     * @param  callable(AssertableElementsList $assertable): void  $callback
+     */
+    public function many(string $selector, callable $callback): static
+    {
+        $callback($this->querySelectorAll($selector));
+
+        return $this;
+    }
+
+    /**
+     * Scope the first assertable element elsewhere in the assertable document matching the given selector.
+     *
+     * @param  callable(AssertableElement $assertable): void  $callback
+     */
+    public function elsewhere(string $selector, callable $callback): static
+    {
+        $document = $this instanceof AssertableDocument
+            ? $this
+            : AssertableDocument::createFromString($this->element->ownerDocument->saveHtml());
+
+        $callback($document->querySelector($selector));
+
+        return $this;
+    }
+}

src/Concerns/Targetable.php

@@ -4,48 +4,16 @@
 
 namespace Ziadoz\AssertableHtml\Concerns;
 
-use Ziadoz\AssertableHtml\Dom\AssertableDocument;
-use Ziadoz\AssertableHtml\Dom\AssertableElement;
-use Ziadoz\AssertableHtml\Dom\AssertableElementsList;
-
 trait Withable
 {
     /**
-     * Scope the first assertable element within the current assertable document or element matching the given selector.
-     *
-     * @param  callable(AssertableElement $assertable): void  $callback
-     */
-    public function with(string $selector, callable $callback): static
-    {
-        $callback($this->querySelector($selector));
-
-        return $this;
-    }
-
-    /**
-     * Scope the matching assertable elements within the current assertable document or element matching the given selector.
+     * Scope with the current assertable, mostly for readability purposes.
      *
-     * @param  callable(AssertableElementsList $assertable): void  $callback
+     * @param  callable(static $assertable): void  $callback
      */
-    public function many(string $selector, callable $callback): static
+    public function with(callable $callback): static
     {
-        $callback($this->querySelectorAll($selector));
-
-        return $this;
-    }
-
-    /**
-     * Scope the first assertable element elsewhere in the assertable document matching the given selector.
-     *
-     * @param  callable(AssertableElement $assertable): void  $callback
-     */
-    public function elsewhere(string $selector, callable $callback): static
-    {
-        $document = $this instanceof AssertableDocument
-            ? $this
-            : AssertableDocument::createFromString($this->element->ownerDocument->saveHtml());
-
-        $callback($document->querySelector($selector));
+        $callback($this);
 
         return $this;
     }

src/Concerns/Withable.php

@@ -9,15 +9,15 @@
 use ErrorException;
 use PHPUnit\Framework\Assert as PHPUnit;
 use Ziadoz\AssertableHtml\Concerns\AssertsDocument;
-use Ziadoz\AssertableHtml\Concerns\Scopeable;
+use Ziadoz\AssertableHtml\Concerns\Targetable;
 use Ziadoz\AssertableHtml\Concerns\Whenable;
 use Ziadoz\AssertableHtml\Concerns\Withable;
 use Ziadoz\AssertableHtml\Exceptions\UnableToCreateAssertableDocument;
 
 final readonly class AssertableDocument
 {
     use AssertsDocument;
-    use Scopeable;
+    use Targetable;
     use Whenable;
     use Withable;
 

src/Dom/AssertableDocument.php

@@ -9,15 +9,15 @@
 use PHPUnit\Framework\Assert as PHPUnit;
 use Ziadoz\AssertableHtml\Concerns\AssertsElement;
 use Ziadoz\AssertableHtml\Concerns\IdentifiesElement;
-use Ziadoz\AssertableHtml\Concerns\Scopeable;
+use Ziadoz\AssertableHtml\Concerns\Targetable;
 use Ziadoz\AssertableHtml\Concerns\Whenable;
 use Ziadoz\AssertableHtml\Concerns\Withable;
 
 readonly class AssertableElement
 {
     use AssertsElement;
     use IdentifiesElement;
-    use Scopeable;
+    use Targetable;
     use Whenable;
     use Withable;
 

src/Dom/AssertableElement.php

@@ -16,14 +16,14 @@
 use RuntimeException;
 use Traversable;
 use Ziadoz\AssertableHtml\Concerns\AssertsElementsList;
-use Ziadoz\AssertableHtml\Concerns\Scopeable;
 use Ziadoz\AssertableHtml\Concerns\Whenable;
+use Ziadoz\AssertableHtml\Concerns\Withable;
 
 final readonly class AssertableElementsList implements ArrayAccess, Countable, IteratorAggregate
 {
     use AssertsElementsList;
-    use Scopeable;
     use Whenable;
+    use Withable;
 
     /** The assertable elements. */
     private array $elements;

src/Dom/AssertableElementsList.php

@@ -21,7 +21,7 @@ public function assertableHtml(): Closure
     public function assertComponent(): Closure
     {
         return function (callable $callback, int $options = LIBXML_HTML_NOIMPLIED, ?string $overrideEncoding = null): static {
-            $this->assertableHtml($options, $overrideEncoding)->scope($callback);
+            $this->assertableHtml($options, $overrideEncoding)->with($callback);
 
             return $this;
         };
@@ -31,7 +31,7 @@ public function assertComponent(): Closure
     public function assertElement(): Closure
     {
         return function (string $selector, callable $callback, int $options = LIBXML_HTML_NOIMPLIED, ?string $overrideEncoding = null): static {
-            $this->assertableHtml($options, $overrideEncoding)->with($selector, $callback);
+            $this->assertableHtml($options, $overrideEncoding)->one($selector, $callback);
 
             return $this;
         };

src/Mixins/TestComponentMixins.php

@@ -28,7 +28,7 @@ public function assertableHtml(): Closure
     public function assertHtml(): Closure
     {
         return function (callable $callback, int $options = 0, ?string $overrideEncoding = null): static {
-            AssertableDocument::createFromString($this->getHtmlContent(), $options, $overrideEncoding)->scope($callback);
+            AssertableDocument::createFromString($this->getHtmlContent(), $options, $overrideEncoding)->with($callback);
 
             return $this;
         };
@@ -38,7 +38,7 @@ public function assertHtml(): Closure
     public function assertHead(): Closure
     {
         return function (callable $callback, int $options = 0, ?string $overrideEncoding = null): static {
-            AssertableDocument::createFromString($this->getHtmlContent(), $options, $overrideEncoding)->with('head', $callback);
+            AssertableDocument::createFromString($this->getHtmlContent(), $options, $overrideEncoding)->one('head', $callback);
 
             return $this;
         };
@@ -48,7 +48,7 @@ public function assertHead(): Closure
     public function assertBody(): Closure
     {
         return function (callable $callback, int $options = 0, ?string $overrideEncoding = null): static {
-            AssertableDocument::createFromString($this->getHtmlContent(), $options, $overrideEncoding)->with('body', $callback);
+            AssertableDocument::createFromString($this->getHtmlContent(), $options, $overrideEncoding)->one('body', $callback);
 
             return $this;
         };
@@ -58,7 +58,7 @@ public function assertBody(): Closure
     public function assertElement(): Closure
     {
         return function (string $selector, callable $callback, int $options = 0, ?string $overrideEncoding = null): static {
-            AssertableDocument::createFromString($this->getHtmlContent(), $options, $overrideEncoding)->with($selector, $callback);
+            AssertableDocument::createFromString($this->getHtmlContent(), $options, $overrideEncoding)->one($selector, $callback);
 
             return $this;
         };

src/Mixins/TestResponseMixins.php

@@ -21,7 +21,7 @@ public function assertableHtml(): Closure
     public function assertView(): Closure
     {
         return function (callable $callback, int $options = LIBXML_HTML_NOIMPLIED, ?string $overrideEncoding = null): static {
-            $this->assertableHtml($options, $overrideEncoding)->scope($callback);
+            $this->assertableHtml($options, $overrideEncoding)->with($callback);
 
             return $this;
         };
@@ -31,7 +31,7 @@ public function assertView(): Closure
     public function assertElement(): Closure
     {
         return function (string $selector, callable $callback, int $options = LIBXML_HTML_NOIMPLIED, ?string $overrideEncoding = null): static {
-            $this->assertableHtml($options, $overrideEncoding)->with($selector, $callback);
+            $this->assertableHtml($options, $overrideEncoding)->one($selector, $callback);
 
             return $this;
         };