Manc / play-mockws

Mock WS client for Play Framework

Table of Contents

• Introduction
• Simple example
• Adding play-mockws to your project
• Usage
• Compatibility matrix
• Release notes

play-mockws

Play MockWS is a mock WS client for Play Framework.

If:

• you write an application in Scala with the Play Framework
• the application makes HTTP calls to external web services with the WS client
• you want to test your implementation

then you can use play-mockws to simulate HTTP requests to external web services in your tests.

Example

// simulation of a GET request to http://dns/url
val ws = MockWS {
  case (GET, "http://dns/url") => Action { Ok("http response") }
}

await(ws.url("http://dns/url").get()).body == "http response"

Adding play-mockws to your project

Add MockWS as test dependency in the build.sbt:

• for Play 2.5.x:

libraryDependencies += "de.leanovate.play-mockws" %% "play-mockws" % "2.5.0-RC2" % "test"

• for Play 2.4.x:

libraryDependencies += "de.leanovate.play-mockws" %% "play-mockws" % "2.4.2" % "test"

• for Play 2.3.x:

libraryDependencies += "de.leanovate.play-mockws" %% "play-mockws" % "2.3.2" % "test"

And use it:

import mockws.MockWS

val ws = MockWS { ... }

Usage

General usage

A MockWS instance can be directly constructed with a partial function like this:

val ws = MockWS {
  case (GET, "/") => Action { Ok("homepage") }
  case (POST, "/users") => Action { request => Created((request.body.asJson.get \ "id").as[String]) }
  case (GET, "/users/24") => Action { NotFound("") }
}

The partial function binds 2 Strings, an HTTP method and the URL, to a Play Action.

For clarity, this partial function is aliased as MockWS.Routes

When calling MockWS.url(), if the HTTP method and the URL are found, the defined play action is evaluated.

Controlling the routes

If you want more control on the routes, for example to know whether a route was called or how many times, use the Route class for this.

Routes can be defined together with the standard function orElse.

val route1 = Route {
  case (GET, "/route1") => Action { Ok("") }
}
val route2 = Route {
  case (GET, "/route2") => Action { Ok("") }
}

val ws = MockWS(route1 orElse route2)

await(ws.url("/route1").get())

route1.called == true
route2.called == false

route1.timeCalled == 1
route2.timeCalled == 0

An example how to structure an implementation to test it with MockWS can be found here.

Other examples can be found in the tests.

Compatibility Matrix

MockWS 2.5.x is actually only compatible with Play 2.5.y., with Scala 2.11. MockWS 2.4.x is actually only compatible with Play 2.4.y., with Scala 2.10 or 2.11. MockWS 2.3.x is actually only compatible with Play 2.3.y., with Scala 2.10 or 2.11.

Release Notes

• 2.5.0 (2016-03-07): release compatible with play 2.5.0
• 2.5.0-RC2:
  • contribution from @avdv: Fix truncated response in FakeWSRequestHolder #15
  • release compatible with play 2.5.0-RC2
• 2.5-RC1: release compatible with play 2.5.0-RC1
• 2.4.2/2.3.2: major contribution from @htmldoug: Replace mockito with a concrete implementation #11
• 2.4.1/2.3.1: contribution from @bomgar: mock sign() method #7
• 2.4.0: first version compatible with play 2.4.y
• 2.3.0: same release as 0.15 - use the same version number as play (2.3.x compatible with play 2.3.y)
• 0.15: fix leanovate#6
• 0.14:
  
  • contribution from @kwark: support for allHeaders + getResponseBodyAsBytes #2
  • contribution from @sebdotv: support for withMethod in execute and stream #3
  • contribution from @knshiro: support for PATCH method #4
  • fix from @jdanbrown: Allow WS varargs to be passed as immutable Seqs #5
• 0.13: handle URL query parameters
• 0.12: remove dependency to specs2 - retain only mockito
• 0.11: add Route