Modern Java DSL for Acceptance Tests using the screenplay pattern
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status Release Version

Flick is an acceptance testing library for Java that implements the Screenplay Pattern, an improvement over the Page Object pattern for UI testing.

At Unruly, we use this to drive our monitoring-in-production specs against our customer-facing Reporting UI.

Getting started with Flick

Install from Maven Central


Using Flick in your tests

A test that implements the FlickDSL interface has access to the given/when/then methods to build a coherent and clean test - these are default methods so classes need not override them. FlickDSL is actually more like a mixin.

public class ExampleTest implements FlickDSL {
   // Tests go here

Screenplay Pattern

Flick abstracts away notions of WebDriver/UI specific code from the test. You can find more detail on the Screenplay Pattern here

Example Test

public void shouldRestrictToDateRange() {
  InternalUser actor = new InternalUser();  // Actor

  final Page page = given(actor.using(browser, ""))
    .wasAbleTo(loginWith(actor.user(), actor.password())) // Logging in as an Action

  when(actor.using(browser, page))
    .attemptsTo(generateReport()) // Generating a report as Action

  then(actor.using(browser, page))
    .should(haveTotalWithValue("LOTS"))) // Inspecting the output as an Assertion

Why would I use Flick/the Screenplay pattern?

The Screenplay pattern guides us towards higher-level abstractions and decoupling from implementation - by encapsulating interactions and validations within interfaces that only expose the Browser.

The implementation can then be refactored without changing the tests outside of swapping in new actions/assertions, leading to less brittle, more robust tests.

Concepts in Flick

A test consists of an Actor interacting with a Stage - we phrase this as Given (an Action is performed), When (an Action is performed), Then (an Assertion must be valid).


An Action is a function that takes a Browser (to interact with) and returns nothing.

For example

class NavigateToPage implements Action {

  private final String url;

  private NavigateToPage(String url) { this.url = url; }

  public void performOn(Browser browser) {

In a more functional style:

public static Action navigateToPage(final String url) {
  return browser -> browser.load(url);


An Assertion is a function that takes a Browser (to interact with) and returns nothing.

public class HasHeader implements Assertion {
    public void check(Browser browser) {

In a more functional style:

public static Assertion hasHeader() {
  return browser -> browser.waitUntil(browser.findElement(By.xpath("//*h1"))::isPresent);