[1.10] Allow usage of XPath in waitForElement (#544)

Co-authored-by: Jonas Hoopmann <jonas.hoopmann@eventim.de>
Co-authored-by: Graham Campbell <GrahamCampbell@users.noreply.github.com>

README.md

@@ -782,6 +782,29 @@ $page->navigate('http://example.com')->waitForNavigation();
 $elem = $page->dom()->search('//div/*/a');
 ```
 
+Wait for an element by CSS selector:
+
+```php
+$page = $browser->createPage();
+$page->navigate('http://example.com')->waitForNavigation();
+
+$page->waitUntilContainsElement('div[data-name=\"el\"]');
+```
+
+If a string is passed to `Page::waitUntilContainsElement`, an instance of
+`CSSSelector` is created for you by `Page::waitForElement`. To use other
+selectors, you can pass an instance of the required `Selector`.
+
+Wait for element by XPath selector:
+
+```php
+$page = $browser->createPage();
+$page->navigate('http://example.com')->waitForNavigation();
+
+$page->waitUntilContainsElement(new XPathSelector('//div[contains(text(), "content")]'));
+```
+
+
 You can send out a text to an element or click on it:
 
 ```php

src/Page.php

@@ -18,10 +18,13 @@
 use HeadlessChromium\Cookies\CookiesCollection;
 use HeadlessChromium\Dom\Dom;
 use HeadlessChromium\Dom\Selector\CssSelector;
+use HeadlessChromium\Dom\Selector\Selector;
 use HeadlessChromium\Exception\CommunicationException;
+use HeadlessChromium\Exception\EvaluationFailed;
 use HeadlessChromium\Exception\InvalidTimezoneId;
 use HeadlessChromium\Exception\JavascriptException;
 use HeadlessChromium\Exception\NoResponseAvailable;
+use HeadlessChromium\Exception\OperationTimedOut;
 use HeadlessChromium\Exception\TargetDestroyed;
 use HeadlessChromium\Input\Keyboard;
 use HeadlessChromium\Input\Mouse;
@@ -457,9 +460,16 @@ private function waitForReloadGenerator($eventName, $loaderId)
     /**
      * Wait until page contains Node.
      *
-     * @throws Exception\OperationTimedOut
+     * @param string|Selector $selectors
+     * @param int             $timeout
+     *
+     * @throws CommunicationException
+     * @throws EvaluationFailed
+     * @throws OperationTimedOut
+     *
+     * @return Page
      */
-    public function waitUntilContainsElement(string $selectors, int $timeout = 30000): self
+    public function waitUntilContainsElement($selectors, int $timeout = 30000): self
     {
         $this->assertNotClosed();
 
@@ -469,18 +479,28 @@ public function waitUntilContainsElement(string $selectors, int $timeout = 30000
     }
 
     /**
+     * @param string|Selector $selectors
+     * @param int             $position
+     *
+     * @throws CommunicationException
+     * @throws EvaluationFailed
+     *
      * @return bool|\Generator
      *
      * @internal
      */
-    public function waitForElement(string $selectors, int $position = 1)
+    public function waitForElement($selectors, int $position = 1)
     {
+        if (!($selectors instanceof Selector)) {
+            $selectors = new CssSelector($selectors);
+        }
+
         $delay = 500;
         $element = [];
 
         while (true) {
             try {
-                $element = Utils::getElementPositionFromPage($this, new CssSelector($selectors), $position);
+                $element = Utils::getElementPositionFromPage($this, $selectors, $position);
             } catch (JavascriptException $exception) {
                 yield $delay;
             }

tests/PageTest.php

@@ -13,13 +13,17 @@
 
 use finfo;
 use HeadlessChromium\BrowserFactory;
+use HeadlessChromium\Dom\Selector\XPathSelector;
 use HeadlessChromium\Exception\InvalidTimezoneId;
 
 /**
  * @covers \HeadlessChromium\Page
  */
 class PageTest extends BaseTestCase
 {
+    private const WAIT_FOR_ELEMENT_HTML = '<div data-name="el">content</div>';
+    private const WAIT_FOR_ELEMENT_RESOURCE_FILE = 'elementLoad.html';
+
     public function testSetViewport(): void
     {
         $factory = new BrowserFactory();
@@ -433,11 +437,29 @@ public function testWaitUntilContainsElement(): void
         $browser = $factory->createBrowser();
         $page = $browser->createPage();
 
-        $page->navigate(self::sitePath('elementLoad.html'))->waitForNavigation();
+        $page->navigate(self::sitePath(self::WAIT_FOR_ELEMENT_RESOURCE_FILE))->waitForNavigation();
+
+        self::assertStringNotContainsString(self::WAIT_FOR_ELEMENT_HTML, $page->getHtml());
 
         $page->waitUntilContainsElement('div[data-name=\"el\"]');
 
-        self::assertStringContainsString('<div data-name="el"></div>', $page->getHtml());
+        self::assertStringContainsString(self::WAIT_FOR_ELEMENT_HTML, $page->getHtml());
+    }
+
+    public function testWaitUntilContainsElementByXPath(): void
+    {
+        $factory = new BrowserFactory();
+
+        $browser = $factory->createBrowser();
+        $page = $browser->createPage();
+
+        $page->navigate(self::sitePath(self::WAIT_FOR_ELEMENT_RESOURCE_FILE))->waitForNavigation();
+
+        self::assertStringNotContainsString(self::WAIT_FOR_ELEMENT_HTML, $page->getHtml());
+
+        $page->waitUntilContainsElement(new XPathSelector('//div[contains(text(), "content")]'));
+
+        self::assertStringContainsString(self::WAIT_FOR_ELEMENT_HTML, $page->getHtml());
     }
 
     public function testSetExtraHTTPHeaders(): void

tests/resources/static-web/elementLoad.html

@@ -11,6 +11,7 @@ <h1>page a</h1>
       let el = document.createElement('div');
 
       el.dataset.name = 'el';
+      el.innerHTML = 'content';
 
       document.body.appendChild(el)
     }, 500)