The first step to build an HTTP request consists of defining the HTTP method and the resource URL to use. For instance, to make an HTTP request on the Items.list action, you will use the GET method and the /items URL, according to your routes file. You could just hard code these values in your test specifications, but that would be a very bad idea for at least two reasons.

First, the mapping between URL shapes and actions is already defined in the routes file. By hard coding the URL and method in your test code, you would be duplicating the information of the routes file, which is bad because you would have to update at two places (in the routes file and in your test code) if you ever wanted to change the mapping of this action.

Second, URLs should be percent encoded, which is a tedious task that you could be tempted to disregard. In the case of the /items URL, this would not be a problem because alphanumeric characters don't need to be encoded.

Hopefully, Play solves both problems by providing a reverse router. While the router dispatches an HTTP request to its corresponding action, the reverse router does the opposite job—it generates the URL and method corresponding to an action call. For instance, you can get the URL and method corresponding to the controllers.Items.list action call as follows:

controllers.routes.Items.list()

This expression returns a Call object containing two fields, url and method, which in our case, are equal to "/items" and "GET", respectively.

It also works with routes that take parameters. The controllers.routes.Items.details(42) expression returns an object with url and method members equal to "/items/42" and "GET", respectively.

The reverse router is automatically generated by the Play sbt plugin each time you change your routes file and guarantees that the URLs you generate are consistent with the routing process and properly encoded. For each action referenced in a route definition, the reverse router generates an object with the same name as the controller in a routes subpackage and contains a method with the same name and signature as in the route definition.

Once you get a Call object that defines the URL and method to use to call the action you want to test, the next step consists of asking the framework to run the routing logic to effectively call the corresponding action. This process is handled by the router, and because it can be overridden by your application, it requires that you start the application. Actually, when you use the run sbt command, Play manages to load and start your application but this is not the case when running tests so you have to manually start your application. Note that manually achieving this also gives you more control over the process. The Scala testing API defines a specs2 scope named play.api.test.WithApplication, which starts the application before running the test content and stops it after the test execution. You can use it as follows:

import play.api.test.WithApplication
"a test specification" in new WithApplication {
  // some code relying on a running application
}

The Java API defines the following equivalent static methods:

import play.test.Helpers;
Helpers.running(Helpers.fakeApplication(), () -> {
  // some code relying on a running application
});

The running helper takes an application as parameter and starts it before evaluating its second parameter.

You now are ready to write specifications against the HTTP layer!

In Scala, I recommend your test classes to extend play.api.test.PlaySpecification instead of org.specs2.mutable.Specification. You will get helper methods to call your actions and inspect their result (for example, in a test/controllers/ItemsSpec.scala file):

package controllers
import play.api.test.{PlaySpecification, FakeRequest, WithApplication}
import play.api.libs.json.Json

class ItemsSpec extends PlaySpecification {
  "Items controller" should {
    "list items" in new WithApplication {
      route(FakeRequest(controllers.routes.Items.list())) match {
        case Some(response) => status(response) must equalTo (OK) contentAsJson(response) must equalTo (Json.arr())
        case None => failure
      }
    }
  }
}

The route method calls the Items.list action using a fake HTTP request and returns its response. Note that the fake request is built using the reverse router. Then, if the routing process succeeds, the status method extracts the response status code and the contentAsJson method reads the response content and parses it as a JSON value. Note that all HTTP standard values (status codes and header names) are also brought by the PlaySpecification trait, allowing us to just write OK instead of 200 to describe a successful status code. In addition to the methods illustrated in the previous code, PlaySpecification also defines helper methods to inspect response headers and in particular cookies and content type.

For Java users, Play provides a class called Helpers with convenient static fields describing HTTP standard values (status codes and header names) and static methods to call controller actions, build requests, and inspect responses:

import org.junit.Test;
import play.mvc.Result;
import static play.test.Helpers.*;
import static org.fest.assertions.Assertions.*;

public class ItemsTest {
  @Test
  public void listItems() {
    running(fakeApplication(), () -> {
      Result response = route(fakeRequest(controllers.routes.Items.list()));
      assertThat(status(response)).isEqualTo(OK);
      assertThat(contentAsString(response)).isEqualTo("[]");
   });
  }
}

I recommend that you import all the helpers using a wildcard static import as shown in the preceding code. The route helper dispatches a given request and returns its response. Then, the status helper method extracts the response status code and the contentAsString method extracts the response body.

Refer to the API documentation of play.api.test.PlaySpecification (play.test.Helpers in Java) for an exhaustive list of supported features.