§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.api.test package or in the Helpers object.

§Testing a template

Since a template is a standard Scala function, you can execute it from your test, and check the result:

"render index template" in {
  val html = views.html.index("Coco")
  
  contentType(html) must equalTo("text/html")
  contentAsString(html) must contain("Hello Coco")
}

§Testing your controllers

You can call any Action code by providing a FakeRequest:

"respond to the index Action" in {
  val result = controllers.Application.index("Bob")(FakeRequest())
  
  status(result) must equalTo(OK)
  contentType(result) must beSome("text/html")
  charset(result) must beSome("utf-8")
  contentAsString(result) must contain("Hello Bob")
}

§Testing the router

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

"respond to the index Action" in {
  val Some(result) = route(FakeRequest(GET, "/Bob"))
  
  status(result) must equalTo(OK)
  contentType(result) must beSome("text/html")
  charset(result) must beSome("utf-8")
  contentAsString(result) must contain("Hello Bob")
}

§Starting a real HTTP server

Sometimes you want to test the real HTTP stack from with your test, in which case you can start a test server:

"run in a server" in new WithServer {
  await(WS.url("http://localhost:" + port).get).status must equalTo(OK)
}

The port value contains the port number the server is running on, by default this is 19001, however you can change
this either by passing the port into the with WithServer constructor, or by setting the system property
testserver.port. This can be useful for integrating with continuous integration servers, so that ports can be
dynamically reserved for each build.

A custom FakeApplication can also be passed to the test server, for example:

"run in a server" in new WithServer(port = 3333, app = FakeApplication(additionalConfiguration = inMemoryDatabase())) {
  await(WS.url("http://localhost:3333").get).status must equalTo(OK)
}

§Testing from within a Web browser.

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

"run in a browser" in new WithBrowser {
  browser.goTo("/")
  browser.$("#title").getTexts().get(0) must equalTo("Hello Guest")
    
  browser.$("a").click()
    
  browser.url must equalTo("/")
  browser.$("#title").getTexts().get(0) must equalTo("Hello Coco")
}

Like WithServer, you can change the port, FakeApplication, and you can also select the web browser to use:

"run in a browser" in new WithBrowser(webDriver = FIREFOX) {
  ...
}

Next: Advanced topics

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.