Documentation

You are viewing the documentation for the 2.3.x release series. The latest stable release series is 3.0.x.

§Writing functional tests

Play provides a number of classes and convenience methods that assist with functional testing. Most of these can be found either in the play.test package or in the Helpers class.

You can add these methods and classes by importing the following:

import play.test.*;
import static play.test.Helpers.*;

§FakeApplication

Play frequently requires a running Application as context: it is usually provided from play.Play.application().

To provide an environment for tests, Play provides a FakeApplication class which can be configured with a different Global object, additional configuration, or even additional plugins.

FakeApplication fakeApp = Helpers.fakeApplication();

FakeApplication fakeAppWithGlobal = fakeApplication(new GlobalSettings() {
  @Override
  public void onStart(Application app) {
    System.out.println("Starting FakeApplication");
  }
});

FakeApplication fakeAppWithMemoryDb = fakeApplication(inMemoryDatabase("test"));

§Testing with a fake application

To run tests within a FakeAppliction, you can do the following:

Java
@Test
public void findById() {
    running(fakeApplication(inMemoryDatabase("test")), new Runnable() {
        public void run() {
            Computer macintosh = Computer.findById(21l);
            assertThat(macintosh.name).isEqualTo("Macintosh");
            assertThat(formatted(macintosh.introduced)).isEqualTo("1984-01-24");
        }
    });
}
Java 8
@Test
public void findById() {
    running(fakeApplication(inMemoryDatabase("test")), () -> {
        Computer macintosh = Computer.findById(21l);
        assertThat(macintosh.name).isEqualTo("Macintosh");
        assertThat(formatted(macintosh.introduced)).isEqualTo("1984-01-24");
    });
}

You can also extend WithApplication, this will automatically ensure that a fake application is started and stopped for you:

public class FunctionalTest extends WithApplication {

§Testing with a server

Sometimes you want to test the real HTTP stack from within your test. You can do this by starting a test server:

Java
@Test
public void testInServer() {
    running(testServer(3333), new Runnable() {
        public void run() {
            assertThat(
                WS.url("http://localhost:3333").get().get(timeout).getStatus()
            ).isEqualTo(OK);
        }
    });
}
Java 8
@Test
public void testInServer() {
    running(testServer(3333), () -> {
        assertThat(
            WS.url("http://localhost:3333").get().get(timeout).getStatus()
        ).isEqualTo(OK);
    });
}

§Testing with a browser

If you want to test your application from with a Web browser, you can use Selenium WebDriver. Play will start the WebDriver for you, and wrap it in the convenient API provided by FluentLenium.

Java
@Test
public void runInBrowser() {
    running(testServer(3333), HTMLUNIT, new Callback<TestBrowser>() {
        public void invoke(TestBrowser browser) {
            browser.goTo("http://localhost:3333");
            assertThat(browser.$("#title").getText()).isEqualTo("Welcome to Play!");
            browser.$("a").click();
            assertThat(browser.url()).isEqualTo("http://localhost:3333/login");
        }
    });
}
Java 8
@Test
public void runInBrowser() {
    running(testServer(3333), HTMLUNIT, browser -> {
        browser.goTo("http://localhost:3333");
        assertThat(browser.$("#title").getText()).isEqualTo("Hello Guest");
        browser.$("a").click();
        assertThat(browser.url()).isEqualTo("http://localhost:3333/login");
    });
}

§Testing the router

Instead of calling the Action yourself, you can let the Router do it:

@Test
public void testBadRoute() {
    Result result = route(fakeRequest(GET, "/xx/Kiki"));
    assertThat(result).isNull();
}

Next: Logging


Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.