Allow assertions against elements by CSS query selector

CHANGELOG.md

@@ -26,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 	`composer require --dev phpunit/phpunit:^9 nunomaduro/collision:^6`
 - Adds database-specific collections with storage of the `found_rows` value.
 - Added testing against `wp_mail()` calls.
+- Added assertions for elements by query selector (`assertElementExistsByQuerySelector()` and `assertElementMissingByQuerySelector()`).
 
 ### Changed
 

composer.json

@@ -30,6 +30,7 @@
         "nette/php-generator": "^3.6.9",
         "nunomaduro/collision": "^6.0 || ^7.0",
         "nunomaduro/termwind": "^1.15.1",
+        "phpgt/cssxpath": "^1.2",
         "psr/container": "^1.1.1 || ^2.0.2",
         "psr/log": "^1.0.1 || ^2.0 || ^3.0",
         "psr/simple-cache": "^3.0",

src/mantle/http/composer.json

@@ -4,7 +4,6 @@
     "type": "library",
     "require": {
         "php": "^8.1",
-        "illuminate/view": "^9.52.15",
         "mantle-framework/contracts": "^1.0",
         "mantle-framework/filesystem": "^1.0",
         "mantle-framework/support": "^1.0",
@@ -36,5 +35,8 @@
     "config": {
         "sort-packages": true
     },
-    "minimum-stability": "dev"
+    "minimum-stability": "dev",
+    "suggest": {
+        "illuminate/view": "For assertions in tests that use Blade templating"
+    }
 }

src/mantle/testing/composer.json

@@ -9,10 +9,11 @@
         "mantle-framework/contracts": "^1.0",
         "mantle-framework/database": "^1.0",
         "mantle-framework/faker": "^1.0",
-        "mantle-framework/http": "^1.0",
         "mantle-framework/http-client": "^1.0",
+        "mantle-framework/http": "^1.0",
         "mantle-framework/support": "^1.0",
         "nunomaduro/termwind": "^1.15.1",
+        "phpgt/cssxpath": "^1.2",
         "spatie/phpunit-snapshot-assertions": "^4.2 || ^5.1"
     },
     "extra": {

src/mantle/testing/concerns/trait-element-assertions.php

@@ -10,6 +10,7 @@
 use PHPUnit\Framework\Assert as PHPUnit;
 use DOMDocument;
 use DOMXPath;
+use Gt\CssXPath\Translator;
 
 /**
  * Assorted Test_Cast assertions for checking for elements in a response.
@@ -46,7 +47,7 @@ protected function get_dom_document(): DOMDocument {
 	 * @param string $expression The XPath expression to execute.
 	 * @return static
 	 */
-	public function assertElementExists( string $expression ) {
+	public function assertElementExists( string $expression ): static {
 		$nodes = ( new DOMXPath( $this->get_dom_document() ) )->query( $expression );
 
 		PHPUnit::assertTrue( ! $nodes ? false : $nodes->length > 0 );
@@ -60,7 +61,7 @@ public function assertElementExists( string $expression ) {
 	 * @param string $id The ID of the element to check.
 	 * @return static
 	 */
-	public function assertElementExistsById( string $id ) {
+	public function assertElementExistsById( string $id ): static {
 		if ( 0 === strpos( $id, '#' ) ) {
 			$id = substr( $id, 1 );
 		}
@@ -74,7 +75,7 @@ public function assertElementExistsById( string $id ) {
 	 * @param string $classname The classname of the element to check.
 	 * @return static
 	 */
-	public function assertElementExistsByClassName( string $classname ) {
+	public function assertElementExistsByClassName( string $classname ): static {
 		if ( 0 === strpos( $classname, '.' ) ) {
 			$classname = substr( $classname, 1 );
 		}
@@ -88,7 +89,7 @@ public function assertElementExistsByClassName( string $classname ) {
 	 * @param string $expression The XPath expression to execute.
 	 * @return static
 	 */
-	public function assertElementMissing( string $expression ) {
+	public function assertElementMissing( string $expression ): static {
 		$nodes = ( new DOMXPath( $this->get_dom_document() ) )->query( $expression );
 
 		PHPUnit::assertTrue( false === $nodes || 0 === $nodes->length );
@@ -102,7 +103,7 @@ public function assertElementMissing( string $expression ) {
 	 * @param string $id The ID of the element to check.
 	 * @return static
 	 */
-	public function assertElementMissingById( string $id ) {
+	public function assertElementMissingById( string $id ): static {
 		if ( 0 === strpos( $id, '#' ) ) {
 			$id = substr( $id, 1 );
 		}
@@ -116,7 +117,7 @@ public function assertElementMissingById( string $id ) {
 	 * @param string $classname The classname of the element to check.
 	 * @return static
 	 */
-	public function assertElementMissingByClassName( string $classname ) {
+	public function assertElementMissingByClassName( string $classname ): static {
 		if ( 0 === strpos( $classname, '.' ) ) {
 			$classname = substr( $classname, 1 );
 		}
@@ -130,7 +131,7 @@ public function assertElementMissingByClassName( string $classname ) {
 	 * @param string $type The type of element to check.
 	 * @return static
 	 */
-	public function assertElementExistsByTagName( string $type ) {
+	public function assertElementExistsByTagName( string $type ): static {
 		return $this->assertElementExists( sprintf( '//*[local-name()="%s"]', $type ) );
 	}
 
@@ -140,7 +141,45 @@ public function assertElementExistsByTagName( string $type ) {
 	 * @param string $type The type of element to check.
 	 * @return static
 	 */
-	public function assertElementMissingByTagName( string $type ) {
+	public function assertElementMissingByTagName( string $type ): static {
 		return $this->assertElementMissing( sprintf( '//*[local-name()="%s"]', $type ) );
 	}
+
+	/**
+	 * Assert that an element exists by query selector.
+	 *
+	 * @param string $selector The selector to use.
+	 * @return static
+	 */
+	public function assertElementExistsByQuerySelector( string $selector ): static {
+		return $this->assertElementExists( new Translator( $selector ) );
+	}
+
+	/**
+	 * Alias for assertElementExistsByQuerySelector.
+	 *
+	 * @param string $selector
+	 */
+	public function assertQuerySelectorExists( string $selector ): static {
+		return $this->assertElementExistsByQuerySelector( $selector );
+	}
+
+	/**
+	 * Assert that an element is missing by query selector.
+	 *
+	 * @param string $selector The selector to use.
+	 * @return static
+	 */
+	public function assertElementMissingByQuerySelector( string $selector ): static {
+		return $this->assertElementMissing( new Translator( $selector ) );
+	}
+
+	/**
+	 * Alias for assertElementMissingByQuerySelector.
+	 *
+	 * @param string $selector
+	 */
+	public function assertQuerySelectorMissing( string $selector ): static {
+		return $this->assertElementMissingByQuerySelector( $selector );
+	}
 }

tests/Testing/Concerns/ElementAssertionsTest.php

@@ -48,4 +48,15 @@ public function test_element_exists_by_tag() {
 		$response->assertElementExistsByTagName( 'section' );
 		$response->assertElementMissingByTagName( 'article' );
 	}
+
+	public function test_element_exists_by_query_selector() {
+		$response = new Test_Response( $this->test_content );
+
+		$response->assertElementExistsByQuerySelector( 'div' );
+		$response->assertElementExistsByQuerySelector( 'section' );
+		$response->assertElementExistsByQuerySelector( '.test-class' );
+		$response->assertElementExistsByQuerySelector( '#test-id' );
+		$response->assertElementMissingByQuerySelector( 'article' );
+		$response->assertElementMissingByQuerySelector( 'aside' );
+	}
 }