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

§Testing your application with ScalaTest

Writing tests for your application can be an involved process. Play provides helpers and application stubs, and ScalaTest provides an integration library, ScalaTest + Play, to make testing your application as easy as possible.

§Overview

The location for tests is in the “test” folder.

You can run tests from the Play console.

To run all tests, run test.
To run only one test class, run test-only followed by the name of the class, i.e., test-only my.namespace.MySpec.
To run only the tests that have failed, run test-quick.
To run tests continually, run a command with a tilde in front, i.e. ~test-quick.
To access test helpers such as FakeRequest in console, run test:console.

Testing in Play is based on SBT, and a full description is available in the testing SBT chapter.

§Using ScalaTest + Play

To use ScalaTest + Play, you’ll need to add it to your build, by changing build.sbt like this:

libraryDependencies ++= Seq(
  "org.scalatestplus.play" %% "scalatestplus-play" % "x.x.x" % Test
)

Where x.x.x is a specific version of scalatestplus-play artifact, for example 5.1.0. See the available releases here.

You do not need to add ScalaTest, or ScalaTest plus mockito to your build explicitly. The proper version of ScalaTest will be brought in automatically as a transitive dependency of ScalaTest + Play. You will, however, need to select a version of ScalaTest + Play that matches your Play version. You can do so by checking the releases compatibility matrix for ScalaTest + Play.

In ScalaTest + Play, you define test classes by extending the PlaySpec trait. Here’s an example:

import org.scalatestplus.play._

import scala.collection.mutable

class StackSpec extends PlaySpec {

  "A Stack" must {
    "pop values in last-in-first-out order" in {
      val stack = new mutable.Stack[Int]
      stack.push(1)
      stack.push(2)
      stack.pop() mustBe 2
      stack.pop() mustBe 1
    }
    "throw NoSuchElementException if an empty stack is popped" in {
      val emptyStack = new mutable.Stack[Int]
      a[NoSuchElementException] must be thrownBy {
        emptyStack.pop()
      }
    }
  }
}

You can alternatively define your own base classes instead of using PlaySpec.

You can run your tests with Play itself, or in IntelliJ IDEA (using the Scala plugin) or in Eclipse (using the Scala IDE and the ScalaTest Eclipse plugin). Please see the IDE page for more details.

§Matchers

PlaySpec mixes in ScalaTest’s MustMatchers, so you can write assertions using ScalaTest’s matchers DSL:

import play.api.test.Helpers._

"Hello world" must endWith ("world")

For more information, see the documentation for MustMatchers.

§Mockito

You can use mocks to isolate unit tests against external dependencies. For example, if your class depends on an external DataService class, you can feed appropriate data to your class without instantiating a DataService object.

ScalaTest provides integration with Mockito via its MockitoSugar trait.

To use Mockito, mix MockitoSugar into your test class and then use the Mockito library to mock dependencies:

case class Data(retrievalDate: java.util.Date)

trait DataService {
  def findData: Data
}

import org.scalatestplus.mockito.MockitoSugar
import org.scalatestplus.play._

import org.mockito.Mockito._

class ExampleMockitoSpec extends PlaySpec with MockitoSugar {

  "MyService#isDailyData" should {
    "return true if the data is from today" in {
      val mockDataService = mock[DataService]
      when(mockDataService.findData).thenReturn(Data(new java.util.Date()))

      val myService = new MyService() {
        override def dataService = mockDataService
      }

      val actual = myService.isDailyData
      actual mustBe true
    }
  }
}

Mocking is especially useful for testing the public methods of classes. Mocking objects and private methods is possible, but considerably harder.

§Unit Testing Models

Play does not require models to use a particular database data access layer. However, if the application uses Anorm or Slick, then frequently the Model will have a reference to database access internally.

import anorm._
import anorm.SqlParser._

case class User(id: String, name: String, email: String) {
   def roles = DB.withConnection { implicit connection =>
      ...
    }
}

For unit testing, this approach can make mocking out the roles method tricky.

A common approach is to keep the models isolated from the database and as much logic as possible, and abstract database access behind a repository layer.

case class Role(name: String)

case class User(id: String, name: String, email: String)

trait UserRepository {
  def roles(user: User): Set[Role]
}

class AnormUserRepository extends UserRepository {
  import anorm._
  import anorm.SqlParser._

  def roles(user:User) : Set[Role] = {
    ...
  }
}

And then access them through services:

class UserService(userRepository: UserRepository) {

  def isAdmin(user: User): Boolean = {
    userRepository.roles(user).contains(Role("ADMIN"))
  }
}

In this way, the isAdmin method can be tested by mocking out the UserRepository reference and passing it into the service:

class UserServiceSpec extends PlaySpec with MockitoSugar {

  "UserService#isAdmin" should {
    "be true when the role is admin" in {
      val userRepository = mock[UserRepository]
      when(userRepository.roles(any[User])).thenReturn(Set(Role("ADMIN")))

      val userService = new UserService(userRepository)

      val actual = userService.isAdmin(User("11", "Steve", "[email protected]"))
      actual mustBe true
    }
  }
}

§Unit Testing Controllers

Since your controllers are just regular classes, you can easily unit test them using Play helpers. If your controllers depends on another classes, using dependency injection will enable you to mock these dependencies. Per instance, given the following controller:

class ExampleController(val controllerComponents: ControllerComponents) extends BaseController {
  def index() = Action {
    Ok("ok")
  }
}

You can test it like:

import scala.concurrent.Future

import org.scalatestplus.play._

import play.api.mvc._
import play.api.test._
import play.api.test.Helpers._

class ExampleControllerSpec extends PlaySpec with Results {

  "Example Page#index" should {
    "should be valid" in {
      val controller             = new ExampleController(Helpers.stubControllerComponents())
      val result: Future[Result] = controller.index().apply(FakeRequest())
      val bodyText: String       = contentAsString(result)
      bodyText mustBe "ok"
    }
  }
}

§Unit Testing EssentialAction

Testing Action or Filter can require testing an EssentialAction (more information about what an EssentialAction is)

For this, the test Helpers.call can be used like that:

class ExampleEssentialActionSpec extends PlaySpec with GuiceOneAppPerSuite {

  implicit lazy val materializer: Materializer   = app.materializer
  implicit lazy val Action: DefaultActionBuilder = app.injector.instanceOf(classOf[DefaultActionBuilder])

  "An essential action" should {
    "can parse a JSON body" in {
      val action: EssentialAction = Action { request =>
        val value = (request.body.asJson.get \ "field").as[String]
        Ok(value)
      }

      val request = FakeRequest(POST, "/").withJsonBody(Json.parse("""{ "field": "value" }"""))

      val result = call(action, request)

      status(result) mustEqual OK
      contentAsString(result) mustEqual "value"
    }
  }
}

Next: Writing functional tests with ScalaTest