Documentation versions (currently viewingVaadin 8)

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Headless Testing

TestBench (3.1 and later) supports fully-featured headless testing with PhantomJS (, a headless browser based on WebKit. It has fast native support for various web standards: JavaScript, DOM handling, CSS selector, JSON, Canvas, and SVG.

Headless testing using PhantomJS allows for around 15% faster test execution without having to start a graphical web browser, even when performing screenshot-based testing! This also makes it possible to run full-scale functional tests on the front-end directly on a build server, without the need to install any web browsers.

It is usually best to use a graphical browser to develop the test cases, as it is possible to see interactively what happens while the tests are being executed. Once the tests are working correctly in a graphical browser, you can migrate them to run on the PhantomJS headless browser.

Basic Setup for Running Headless Tests

The only set up required is to install the PhantomJS binary. Follow the instructions for your operating system at PhantomJS download page, and place the binary in the system path.

The PhantomJSDriver dependency is already included in Vaadin TestBench.

Creating a Headless WebDriver Instance

Creating an instance of the PhantomJSDriver is just as easy as creating an instance of FirefoxDriver.

    new PhantomJSDriver()));

Some tests may fail because of the small default window size in PhantomJS. Such tests are, for example, tests containing elements that pop up and might go off-screen when the window is small. To make them work better, specify a size for the window:

        new Dimension(1024, 768));

Nothing else is needed to run tests headlessly.

Running Headless Tests in a Distributed Environment

Running PhantomJS in a distributed grid is equally easy. First, install PhantomJS in the nodes by following the instructions in Basic Setup for Running Headless Tests. Then, start PhantomJS using the following command:

phantomjs --webdriver=8080 \

The above will start PhantomJS in the WebDriver mode and register it with a grid hub running at After this, running tests in the grid is as easy as passing DesiredCapabilities.phantomjs() to the RemoteWebDriver constructor.

setDriver(new RemoteWebDriver(