Se-nimatograph by Dima

The Selenium Driver (for Java) has four functions to work with screenshots:

- captureScreenshot(filename)
- captureScreenshotToString()
- captureEntirePageScreenshot(filename, kwargs)
- captureEntirePageScreenshotToString(kwargs)

Let’s work out how they differ from each other, and in what cases they are best to use.

The function captureScreenshot(filename) makes a png format screenshot and saves it to the file. The big disadvantage of this function is that it saves a standard screenshot, you would get the same result by pressing “Print screen” button.

This means that if your browser window is minimized or not maximized then the page or a section of it will not be seen on the screenshot. Even if the browser is opened completely, but the page is too long (or too wide) and you have to scroll through it, again only the visible part of the page will be on the screenshot.


Fig. 1 – screenshot by captureScreenshot()

However captureEntirePageScreenshot(filename, kwargs) is free from these disadvantages. The creation of a screenshot is done by the browser itself so the screenshot contains the whole page, as the browser sees it.


Fig. 2 – screenshot by captureEntirePageScreenshot()

The extra parameter kwargs allows you to set the colour of the background. The pitty thing is that the only browsers that create screenshots are Firefox (nothing extra required) and IE (if you install the plugin).

For creating screenshots in our SalesForce tests we use that function, and honestly, we missed the fact that it doesn’t work with all browsers. The tests won’t fail and will give you a warning that a screenshot couldn’t be made but there won’t be any pictures.

In our case the problem is solved by adding the conditions of using the first or second function to the CommonActions.getScreenshot(), depending on the browser:

if (browser == "*chrome" || browser == "*iehta") {
    seleniumInstance.captureEntirePageScreenshot(filename, "");
else {

By the way, to workaround captureScreenshot() limit we can open the browser completely with the function windowMaximize(). This way you will be certain that the browser can be seen, but areas behind scrolling will not be visible anyway.

Let’s talk about captureScreenshotToString() and captureEntirePageToString() now.

If the tests are executed on the Selenium Grid (a Hub and one or more RC), then the saving of screenshots for these functions is done by RC. If the Hub and RC are located on the same machine, you probably won’t even notice it. But if your Selenium Hub is located on one box and the RC is on another, you must take this into account because the screenshots will be saved to the box that the RC is running on. If you specify only the name of the file, as a parameter, it will be saved on the RC box. If you use an absolute path, for example: “C:\screenshots\screen_1.png”, then you must be sure that the directory on the RCs’ machine exists, otherwise an exception will be generated.

But! In the case of a remote RC, it would be good to get the screenshots on the machine where tests are ran, and not having to copy all of them from different RCs after tests completion. CaptureScreenToString() and captureEntirePageScreenshotToString() functions allow us to do just that. Instead of saving the screenshot to the file, they return a string which contains the screenshot encoded in base64. Everything that’s left to do is; decode the screenshot and save it to file, now in any location we want.

This is how the function for decoding and saving the screenshot will look:

import sun.misc.BASE64Decoder;
public static boolean decodeAndWriteScreenshot(String screen, String filename) {
   if (screen==null) {
      return false;
   BASE64Decoder decoder = new BASE64Decoder();
   byte[] decoded;
   OutputStream out;
   try {
      decoded = decoder.decodeBuffer(screen);
       out = new FileOutputStream(filename);
       try {
       } finally {
   } catch (Exception E){
      return false;
   return true;

In the example sun.misc.BASE64Decoder is used, notice that its use isn’t recommended.

The function captureEntirePageScreenshotToString() might not be in other than Java Selenium Drivers. For example, this function is not included in PHP Driver.

As you can see, the most universal function for receiving screenshots (it will work for all drivers, all browsers, and will allow the screenshot to be saved on the machine where the test is run) is captureScreenshotToString().

You can see for yourself the differences between captureScreenshotToString() and CaptureEntirePageScreenshotToString() by aiming them to your site. Simply download this example (Java code) and change the webSite value.

Print this post | Home

One comment

  1. Jimmy says:

    Скачал альфа-версию php-драйвера testing_selenium v 0.4.4. В нем не оказалось метода captureScreenshotToString(), был только captureScreenshot().