Documentation versions (currently viewingVaadin 23)

UI Unit Testing


UI unit testing removes the necessity to run both the browser and the servlet container, to test your Vaadin-based applications faster.

  • container-less testing: You do not need to launch the servlet container. UI unit testing creates the Vaadin Session, the UI and other necessary Vaadin classes straight in the JVM which runs your JUnit tests.

  • browser-less testing: You look up components straight from UI.getCurrent(), bypassing the browser and the JavaScript→Server bridge. You call methods directly on your server-side View classes and on the server-side Java Vaadin components.

Why Unit Testing?

Advantages of unit testing over end-to-end testing with TestBench:

  • Fast: browser-less tests are typically 100x faster than Selenium-based tests and run in 5 to 60 milliseconds, depending on their complexity.

  • Reliable: no arbitrary sleeps are needed, as the test is executed on the server side and it can await until the request is fully processed. No random failures because of incompatibility between the Selenium drivers and the browser.

  • Headless: the tests run headless, as there is no browser. No need to set up the screen in your CI environment.

  • Robust: the test runs in the same JVM as the server-side components. If the server-side bootstrap fails and throws an exception, the test method fails with the same exception. No need to go hunting for exceptions in a log located somewhere on a CI server.

  • No need to write a massive set of Page Objects. You are already on the server, and you have access to the actual Java components that are already providing you with high-level APIs, exactly as Page Objects do.

  • Full access to the database. You are on the server side, so you can access the database from your tests in the same way your business logic accesses the database. You can run a bunch of SQL statements to restore the database to a known state before every test. Even better, you can run the test in a transaction, then roll back after the test, to perform a fast database revert to a known state.

With this technique you can run 600 UI tests in 7 seconds, as opposed to 1 to 2 hours with a Selenium-based approach. Because of the speed, you can let the UI tests run after every commit via your continuous integration server. Bypassing the browser and talking to the Vaadin server API directly eliminates the need to start the servlet container. You can add the server JARs to the testing classpath and call the Vaadin server API, which, in turn, invokes your server logic.


UI unit testing is designed to bypass the browser and the servlet container. This means that it is impossible to test JavaScript code, templates and other client-side functionalities. If you need to test client-side features, you need to use browser-based integration tests with TestBench.