Merge pull request #701 from sapzape/take-element-screenshot

Add take element screenshot command

Author: OndraM

CHANGELOG.md

@@ -5,7 +5,8 @@ This project versioning adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 - Experimental W3C WebDriver protocol support. The protocol will be used automatically when remote end (like Geckodriver, newer Chromedriver etc.) supports it.
-- `getStatus()` method of RemoteWebDriver to get information about remote-end readiness to create new sessions.
+- `getStatus()` method of `RemoteWebDriver` to get information about remote-end readiness to create new sessions.
+- `takeElementScreenshot()` method of `RemoteWebElement` to do the obvious - take screenshot of the particular element.
 
 ### Changed
 - Revert no longer needed workaround for Chromedriver bug [2943](https://bugs.chromium.org/p/chromedriver/issues/detail?id=2943).

lib/Remote/DriverCommand.php

@@ -149,6 +149,7 @@ class DriverCommand
     // W3C specific
     const ACTIONS = 'actions';
     const GET_ELEMENT_PROPERTY = 'getElementProperty';
+    const TAKE_ELEMENT_SCREENSHOT = 'takeElementScreenshot';
 
     private function __construct()
     {

lib/Remote/HttpCommandExecutor.php

@@ -129,6 +129,10 @@ class HttpCommandExecutor implements WebDriverCommandExecutor
         DriverCommand::STATUS => ['method' => 'GET', 'url' => '/status'],
         DriverCommand::SUBMIT_ELEMENT => ['method' => 'POST', 'url' => '/session/:sessionId/element/:id/submit'],
         DriverCommand::SCREENSHOT => ['method' => 'GET', 'url' => '/session/:sessionId/screenshot'],
+        DriverCommand::TAKE_ELEMENT_SCREENSHOT => [
+            'method' => 'GET',
+            'url' => '/session/:sessionId/element/:id/screenshot',
+        ],
         DriverCommand::TOUCH_SINGLE_TAP => ['method' => 'POST', 'url' => '/session/:sessionId/touch/click'],
         DriverCommand::TOUCH_DOWN => ['method' => 'POST', 'url' => '/session/:sessionId/touch/down'],
         DriverCommand::TOUCH_DOUBLE_TAP => ['method' => 'POST', 'url' => '/session/:sessionId/touch/doubleclick'],

lib/Remote/RemoteWebElement.php

@@ -431,6 +431,33 @@ public function getID()
         return $this->id;
     }
 
+    /**
+     * Take screenshot of a specific element.
+     *
+     * @param string $save_as The path of the screenshot to be saved.
+     * @return string The screenshot in PNG format.
+     */
+    public function takeElementScreenshot($save_as = null)
+    {
+        $screenshot = base64_decode(
+            $this->executor->execute(
+                DriverCommand::TAKE_ELEMENT_SCREENSHOT,
+                [':id' => $this->id]
+            )
+        );
+
+        if ($save_as) {
+            $directoryPath = dirname($save_as);
+            if (!file_exists($directoryPath)) {
+                mkdir($directoryPath, 0777, true);
+            }
+
+            file_put_contents($save_as, $screenshot);
+        }
+
+        return $screenshot;
+    }
+
     /**
      * Test if two element IDs refer to the same DOM element.
      *

lib/WebDriverElement.php

@@ -132,4 +132,13 @@ public function submit();
      * @return string The opaque ID.
      */
     public function getID();
+
+    /**
+     * Take screenshot of a specific element.
+     *
+     * @param string $save_as The path of the screenshot to be saved.
+     * @return string The screenshot in PNG format.
+     * @todo Add in next major release (BC)
+     */
+    //public function takeElementScreenshot($save_as = null);
 }

tests/functional/RemoteWebElementTest.php

@@ -17,6 +17,7 @@
 
 use Facebook\WebDriver\Exception\NoSuchElementException;
 use Facebook\WebDriver\Remote\RemoteWebElement;
+use Facebook\WebDriver\Remote\WebDriverBrowserType;
 
 /**
  * @coversDefaultClass \Facebook\WebDriver\Remote\RemoteWebElement
@@ -336,4 +337,49 @@ public function testShouldFindMultipleChildElements()
         $this->assertCount(3, $childElements); // but we should find only subelements of one <ul>
         $this->assertContainsOnlyInstancesOf(RemoteWebElement::class, $childElements);
     }
+
+    /**
+     * @covers ::takeElementScreenshot
+     * @group exclude-saucelabs
+     */
+    public function testShouldTakeAndSaveElementScreenshot()
+    {
+        self::skipForJsonWireProtocol('Take element screenshot is only part of W3C protocol');
+
+        if (!extension_loaded('gd')) {
+            $this->markTestSkipped('GD extension must be enabled');
+        }
+        if ($this->desiredCapabilities->getBrowserName() === WebDriverBrowserType::HTMLUNIT) {
+            $this->markTestSkipped('Screenshots are not supported by HtmlUnit browser');
+        }
+
+        // Intentionally save screenshot to subdirectory to tests it is being created
+        $screenshotPath = sys_get_temp_dir() . '/' . uniqid('php-webdriver-') . '/element-screenshot.png';
+
+        $this->driver->get($this->getTestPageUrl('index.html'));
+
+        $element = $this->driver->findElement(WebDriverBy::id('red-box'));
+
+        $outputPngString = $element->takeElementScreenshot($screenshotPath);
+
+        // Assert file output
+        $imageFromFile = imagecreatefrompng($screenshotPath);
+        $this->assertEquals(5, imagesx($imageFromFile));
+        $this->assertEquals(5, imagesy($imageFromFile));
+
+        // Validate element is actually red
+        $this->assertSame(
+            ['red' => 255, 'green' => 0, 'blue' => 0, 'alpha' => 0],
+            imagecolorsforindex($imageFromFile, imagecolorat($imageFromFile, 0, 0))
+        );
+
+        // Assert string output
+        $imageFromString = imagecreatefromstring($outputPngString);
+        $this->assertInternalType('resource', $imageFromString);
+        $this->assertEquals(5, imagesx($imageFromString));
+        $this->assertEquals(5, imagesy($imageFromString));
+
+        unlink($screenshotPath);
+        rmdir(dirname($screenshotPath));
+    }
 }