Embrace strict(er) types, ensure that #13 is covered by Selector

src/Constraints/SelectorCount.php

@@ -49,7 +49,7 @@ public function toString(): string
      * Evaluates the constraint for parameter $other. Returns true if the
      * constraint is met, false otherwise.
      *
-     * @param mixed $other value or object to evaluate
+     * @param mixed $html value or object to evaluate
      *
      * @return bool
      */

src/MarkupAssertionsTrait.php

@@ -22,14 +22,17 @@ trait MarkupAssertionsTrait
      *
      * @since 1.0.0
      *
-     * @param string $selector A query selector for the element to find.
-     * @param string $markup   The output that should contain the $selector.
-     * @param string $message  A message to display if the assertion fails.
+     * @param string|array<string, scalar> $selector A query selector to search for.
+     * @param string                       $markup   The output that should contain the $selector.
+     * @param string                       $message  A message to display if the assertion fails.
      *
      * @return void
      */
-    public function assertContainsSelector($selector, $markup = '', $message = '')
-    {
+    public function assertContainsSelector(
+        $selector,
+        string $markup = '',
+        string $message = ''
+    ): void {
         $constraint = new ContainsSelector(new Selector($selector));
 
         static::assertThat($markup, $constraint, $message);
@@ -40,14 +43,17 @@ public function assertContainsSelector($selector, $markup = '', $message = '')
      *
      * @since 1.0.0
      *
-     * @param string $selector A query selector for the element to find.
-     * @param string $markup   The output that should not contain the $selector.
-     * @param string $message  A message to display if the assertion fails.
+     * @param string|array<string, scalar> $selector A query selector to search for.
+     * @param string                       $markup   The output that should not contain the $selector.
+     * @param string                       $message  A message to display if the assertion fails.
      *
      * @return void
      */
-    public function assertNotContainsSelector($selector, $markup = '', $message = '')
-    {
+    public function assertNotContainsSelector(
+        $selector,
+        string $markup = '',
+        string $message = ''
+    ): void {
         $constraint = new LogicalNot(new ContainsSelector(new Selector($selector)));
 
         static::assertThat($markup, $constraint, $message);
@@ -58,15 +64,19 @@ public function assertNotContainsSelector($selector, $markup = '', $message = ''
      *
      * @since 1.0.0
      *
-     * @param int    $count    The number of matching elements expected.
-     * @param string $selector A query selector for the element to find.
-     * @param string $markup   The markup to run the assertion against.
-     * @param string $message  A message to display if the assertion fails.
+     * @param int                          $count    The number of matching elements expected.
+     * @param string|array<string, scalar> $selector A query selector to search for.
+     * @param string                       $markup   The markup to run the assertion against.
+     * @param string                       $message  A message to display if the assertion fails.
      *
      * @return void
      */
-    public function assertSelectorCount($count, $selector, $markup = '', $message = '')
-    {
+    public function assertSelectorCount(
+        int $count,
+        $selector,
+        string $markup = '',
+        string $message = ''
+    ): void {
         $constraint = new SelectorCount(new Selector($selector), $count);
 
         static::assertThat($markup, $constraint, $message);
@@ -85,8 +95,11 @@ public function assertSelectorCount($count, $selector, $markup = '', $message =
      *
      * @return void
      */
-    public function assertHasElementWithAttributes($attributes = [], $markup = '', $message = '')
-    {
+    public function assertHasElementWithAttributes(
+        array $attributes = [],
+        string $markup = '',
+        string $message = ''
+    ): void {
         $constraint = new ContainsSelector(new Selector($attributes));
 
         static::assertThat($markup, $constraint, $message);
@@ -105,8 +118,11 @@ public function assertHasElementWithAttributes($attributes = [], $markup = '', $
      *
      * @return void
      */
-    public function assertNotHasElementWithAttributes($attributes = [], $markup = '', $message = '')
-    {
+    public function assertNotHasElementWithAttributes(
+        $attributes = [],
+        $markup = '',
+        $message = ''
+    ): void {
         $constraint = new LogicalNot(new ContainsSelector(new Selector($attributes)));
 
         static::assertThat($markup, $constraint, $message);
@@ -117,15 +133,19 @@ public function assertNotHasElementWithAttributes($attributes = [], $markup = ''
      *
      * @since 1.1.0
      *
-     * @param string $contents The string to look for within the DOM node's contents.
-     * @param string $selector A query selector for the element to find.
-     * @param string $markup   The output that should contain the $selector.
-     * @param string $message  A message to display if the assertion fails.
+     * @param string                       $contents The string to look for within the DOM node's contents.
+     * @param string|array<string, scalar> $selector A query selector to search for.
+     * @param string                       $markup   The output that should contain the $selector.
+     * @param string                       $message  A message to display if the assertion fails.
      *
      * @return void
      */
-    public function assertElementContains($contents, $selector = '', $markup = '', $message = '')
-    {
+    public function assertElementContains(
+        string $contents,
+        $selector = '',
+        string $markup = '',
+        string $message = ''
+    ): void {
         $constraint = new ElementContainsString(new Selector($selector), $contents);
 
         static::assertThat($markup, $constraint, $message);
@@ -136,15 +156,19 @@ public function assertElementContains($contents, $selector = '', $markup = '', $
      *
      * @since 1.1.0
      *
-     * @param string $contents The string to look for within the DOM node's contents.
-     * @param string $selector A query selector for the element to find.
-     * @param string $markup   The output that should not contain the $selector.
-     * @param string $message  A message to display if the assertion fails.
+     * @param string                       $contents The string to look for within the DOM node's contents.
+     * @param string|array<string, scalar> $selector A query selector to search for.
+     * @param string                       $markup   The output that should not contain the $selector.
+     * @param string                       $message  A message to display if the assertion fails.
      *
      * @return void
      */
-    public function assertElementNotContains($contents, $selector = '', $markup = '', $message = '')
-    {
+    public function assertElementNotContains(
+        string $contents,
+        $selector = '',
+        string $markup = '',
+        string $message = ''
+    ): void {
         $constraint = new LogicalNot(new ElementContainsString(new Selector($selector), $contents));
 
         static::assertThat($markup, $constraint, $message);
@@ -155,15 +179,19 @@ public function assertElementNotContains($contents, $selector = '', $markup = ''
      *
      * @since 1.1.0
      *
-     * @param string $regexp   The regular expression pattern to look for within the DOM node.
-     * @param string $selector A query selector for the element to find.
-     * @param string $markup   The output that should contain the $selector.
-     * @param string $message  A message to display if the assertion fails.
+     * @param string                       $regexp   The regular expression pattern to look for within the DOM node.
+     * @param string|array<string, scalar> $selector A query selector to search for.
+     * @param string                       $markup   The output that should contain the $selector.
+     * @param string                       $message  A message to display if the assertion fails.
      *
      * @return void
      */
-    public function assertElementRegExp($regexp, $selector = '', $markup = '', $message = '')
-    {
+    public function assertElementRegExp(
+        string $regexp,
+        $selector = '',
+        string $markup = '',
+        string $message = ''
+    ): void {
         $constraint = new ElementMatchesRegExp(new Selector($selector), $regexp);
 
         static::assertThat($markup, $constraint, $message);
@@ -174,15 +202,19 @@ public function assertElementRegExp($regexp, $selector = '', $markup = '', $mess
      *
      * @since 1.1.0
      *
-     * @param string $regexp   The regular expression pattern to look for within the DOM node.
-     * @param string $selector A query selector for the element to find.
-     * @param string $markup   The output that should not contain the $selector.
-     * @param string $message  A message to display if the assertion fails.
+     * @param string                       $regexp   The regular expression pattern to look for within the DOM node.
+     * @param string|array<string, scalar> $selector A query selector to search for.
+     * @param string                       $markup   The output that should not contain the $selector.
+     * @param string                       $message  A message to display if the assertion fails.
      *
      * @return void
      */
-    public function assertElementNotRegExp($regexp, $selector = '', $markup = '', $message = '')
-    {
+    public function assertElementNotRegExp(
+        string $regexp,
+        $selector = '',
+        string $markup = '',
+        string $message = ''
+    ): void {
         $constraint = new LogicalNot(new ElementMatchesRegExp(new Selector($selector), $regexp));
 
         static::assertThat($markup, $constraint, $message);

src/Selector.php

@@ -38,7 +38,7 @@ public function __construct($selector)
      *
      * @return string
      */
-    public function __toString()
+    public function __toString(): string
     {
         return $this->getValue();
     }
@@ -48,7 +48,7 @@ public function __toString()
      *
      * @return string
      */
-    public function getValue()
+    public function getValue(): string
     {
         return $this->selector;
     }
@@ -61,7 +61,7 @@ public function getValue()
      *
      * @return string The flattened attribute array.
      */
-    private function attributeArrayToString($attributes)
+    private function attributeArrayToString(array $attributes): string
     {
         if (empty($attributes)) {
             throw new AttributeArrayException('Attributes array is empty.');

tests/Integration/AssertionsTest.php

@@ -30,7 +30,7 @@ class MarkupAssertionsTraitTest extends TestCase
 </main>
 HTML;
 
-    public function testPresenceOfSelectors()
+    public function testPresenceOfSelectors(): void
     {
         $this->assertContainsSelector('main', $this->markup);
         $this->assertContainsSelector('h1', $this->markup);
@@ -57,7 +57,7 @@ public function testPresenceOfSelectors()
         );
     }
 
-    public function testMatchingContentsOfSelectors()
+    public function testMatchingContentsOfSelectors(): void
     {
         $this->assertElementContains('Good news', 'main', $this->markup);
         $this->assertElementContains('Good news', 'h1', $this->markup);

tests/Unit/Constraints/ContainsSelectorTest.php

@@ -19,7 +19,7 @@ class ContainsSelectorTest extends TestCase
      * @test
      * @dataProvider provideSelectorVariants
      */
-    public function it_should_find_matching_selectors_in_content($selector)
+    public function it_should_find_matching_selectors_in_content(string $selector): void
     {
         $constraint = new ContainsSelector(new Selector($selector));
         $html = '<a href="https://example.com" id="my-link" class="link another-class">Example</a>';
@@ -31,7 +31,7 @@ public function it_should_find_matching_selectors_in_content($selector)
      * @test
      * @dataProvider provideSelectorVariants
      */
-    public function it_should_not_find_unmatched_selectors_in_content($selector)
+    public function it_should_not_find_unmatched_selectors_in_content(string $selector): void
     {
         $constraint = new ContainsSelector(new Selector($selector));
         $html = '<h1 id="page-title" class="foo bar">This element has little to do with the link.</h1>';
@@ -42,7 +42,7 @@ public function it_should_not_find_unmatched_selectors_in_content($selector)
     /**
      * @test
      */
-    public function it_should_fail_with_a_useful_error_message()
+    public function it_should_fail_with_a_useful_error_message(): void
     {
         $selector = new Selector('p');
         $html = '<h1>Some Title</h1>';
@@ -65,7 +65,7 @@ public function it_should_fail_with_a_useful_error_message()
      *
      * @return iterable<string,array<string>>
      */
-    public function provideSelectorVariants()
+    public function provideSelectorVariants(): iterable
     {
         yield 'Simple tag name' => ['a'];
         yield 'Class name' => ['.link'];

tests/Unit/Constraints/ElementContainsStringTest.php

@@ -18,7 +18,7 @@ class ElementContainsStringTest extends TestCase
     /**
      * @test
      */
-    public function it_should_match_a_string_in_the_given_markup()
+    public function it_should_match_a_string_in_the_given_markup(): void
     {
         $constraint = new ElementContainsString(new Selector('p'), 'This is the content', true);
         $html = '<h1>Title</h1><p>This is the content</p>';
@@ -29,7 +29,7 @@ public function it_should_match_a_string_in_the_given_markup()
     /**
      * @test
      */
-    public function it_should_match_in_a_case_sensitive_manner_by_default()
+    public function it_should_match_in_a_case_sensitive_manner_by_default(): void
     {
         $constraint = new ElementContainsString(new Selector('p'), 'THIS IS THE CONTENT');
         $html = '<h1>Title</h1><p>This is the content</p>';
@@ -43,7 +43,7 @@ public function it_should_match_in_a_case_sensitive_manner_by_default()
     /**
      * @test
      */
-    public function it_should_be_able_to_ignore_case()
+    public function it_should_be_able_to_ignore_case(): void
     {
         $constraint = new ElementContainsString(new Selector('p'), 'THIS IS THE CONTENT', true);
         $html = '<h1>Title</h1><p>This is the content</p>';
@@ -57,7 +57,7 @@ public function it_should_be_able_to_ignore_case()
     /**
      * @test
      */
-    public function it_should_fail_if_no_match_is_found()
+    public function it_should_fail_if_no_match_is_found(): void
     {
         $constraint = new ElementContainsString(new Selector('p'), 'This is the content');
         $html = '<h1>This is the content</h1><p>But this is not</p>';
@@ -72,7 +72,7 @@ public function it_should_fail_if_no_match_is_found()
      *
      * @ticket https://github.com/stevegrunwell/phpunit-markup-assertions/issues/31
      */
-    public function it_should_be_able_to_handle_various_character_sets($greeting)
+    public function it_should_be_able_to_handle_various_character_sets(string $greeting): void
     {
         $constraint = new ElementContainsString(new Selector('h1'), $greeting);
         $html = sprintf('<div><h1>%s</h1></div>', $greeting);
@@ -83,7 +83,7 @@ public function it_should_be_able_to_handle_various_character_sets($greeting)
     /**
      * @test
      */
-    public function it_should_test_against_the_inner_contents_of_the_found_nodes()
+    public function it_should_test_against_the_inner_contents_of_the_found_nodes(): void
     {
         $constraint = new ElementContainsString(new Selector('p'), 'class');
         $html = '<p class="first">First</p><p class="second">Second</p>';
@@ -97,7 +97,7 @@ public function it_should_test_against_the_inner_contents_of_the_found_nodes()
     /**
      * @test
      */
-    public function it_should_fail_with_a_useful_error_message()
+    public function it_should_fail_with_a_useful_error_message(): void
     {
         $html = '<p>Some other string</p>';
         $expected = <<<'MSG'
@@ -121,7 +121,7 @@ public function it_should_fail_with_a_useful_error_message()
     /**
      * @test
      */
-    public function it_should_include_all_relevant_matches_in_error_messages()
+    public function it_should_include_all_relevant_matches_in_error_messages(): void
     {
         $html = '<p>Some other string</p><p>Yet another string</p>';
         $expected = <<<'MSG'
@@ -146,7 +146,7 @@ public function it_should_include_all_relevant_matches_in_error_messages()
     /**
      * @test
      */
-    public function it_should_provide_a_simple_error_message_if_no_selector_matches_are_found()
+    public function it_should_provide_a_simple_error_message_if_no_selector_matches_are_found(): void
     {
         $html = '<p>Some other string</p><p>Yet another string</p>';
         $expected = "Failed asserting that any elements match selector 'h1'.";
@@ -164,9 +164,9 @@ public function it_should_provide_a_simple_error_message_if_no_selector_matches_
     /**
      * Provide a list of strings in various language.
      *
-     * @return Iterable<string,array<string>>
+     * @return iterable<string,array<string>>
      */
-    public function provideGreetingsInDifferentLanguages()
+    public function provideGreetingsInDifferentLanguages(): iterable
     {
         yield 'Arabic'    => ['مرحبا!'];
         yield 'Chinese'   => ['你好'];