+doc add Java testkit documentation and scaladoc

akka-docs-dev/rst/java/code/docs/http/javadsl/testkit/MyAppService.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright (C) 2009-2015 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.http.javadsl.testkit;
+
+//#simple-app
+import akka.http.javadsl.server.*;
+import akka.http.javadsl.server.values.Parameters;
+
+public class MyAppService extends HttpApp {
+    RequestVal<Double> x = Parameters.doubleValue("x");
+    RequestVal<Double> y = Parameters.doubleValue("y");
+
+    public RouteResult add(RequestContext ctx, double x, double y) {
+        return ctx.complete("x + y = " + (x + y));
+    }
+
+    @Override
+    public Route createRoute() {
+        return
+            route(
+                get(
+                    pathPrefix("calculator").route(
+                        path("add").route(
+                            handleReflectively(this, "add", x, y)
+                        )
+                    )
+                )
+            );
+    }
+}
+//#simple-app

akka-docs-dev/rst/java/code/docs/http/javadsl/testkit/TestkitExampleTest.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2009-2015 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.http.javadsl.testkit;
+
+//#simple-app-testing
+import akka.http.javadsl.model.HttpRequest;
+import akka.http.javadsl.model.StatusCodes;
+import akka.http.javadsl.testkit.JUnitRouteTest;
+import akka.http.javadsl.testkit.TestRoute;
+import org.junit.Test;
+
+public class TestkitExampleTest extends JUnitRouteTest {
+    TestRoute appRoute = testRoute(new MyAppService().createRoute());
+
+    @Test
+    public void testCalculatorAdd() {
+        // test happy path
+        appRoute.run(HttpRequest.GET("/calculator/add?x=4.2&y=2.3"))
+            .assertStatusCode(200)
+            .assertEntity("x + y = 6.5");
+
+        // test responses to potential errors
+        appRoute.run(HttpRequest.GET("/calculator/add?x=3.2"))
+            .assertStatusCode(StatusCodes.NOT_FOUND) // 404
+            .assertEntity("Request is missing required query parameter 'y'");
+
+        // test responses to potential errors
+        appRoute.run(HttpRequest.GET("/calculator/add?x=3.2&y=three"))
+            .assertStatusCode(StatusCodes.BAD_REQUEST)
+            .assertEntity("The query parameter 'y' was malformed:\n" +
+                    "'three' is not a valid 64-bit floating point value");
+    }
+}
+//#simple-app-testing

akka-docs-dev/rst/java/http/routing-dsl/index.rst

@@ -14,4 +14,5 @@ To use the high-level API you need to add a dependency to the ``akka-http-experi
    request-vals/index
    handlers
    marshalling
+   testkit
    json-jackson-support

akka-docs-dev/rst/java/http/routing-dsl/overview.rst

@@ -68,4 +68,9 @@ to HTTP entities.
 
 Read more about :ref:`marshalling-java`.
 
+akka-http contains a testkit that simplifies testing routes. It allows to run test-requests against (sub-)routes
+quickly without running them over the network and helps with writing assertions on HTTP response properties.
+
+Read more about :ref:`http-testkit-java`.
+
 .. _DRY: http://en.wikipedia.org/wiki/Don%27t_repeat_yourself

akka-docs-dev/rst/java/http/routing-dsl/testkit.rst

@@ -0,0 +1,80 @@
+.. _http-testkit-java:
+
+Route Testkit
+=============
+
+akka-http has a testkit that provides a convenient way of testing your routes with JUnit. It allows
+running requests against a route (without hitting the network) and provides means to assert against
+response properties in a compact way.
+
+To use the testkit you need to take these steps:
+
+* add a dependency to the ``akka-http-testkit-experimental`` module
+* derive the test class from ``JUnitRouteTest``
+* wrap the route under test with ``RouteTest.testRoute`` to create a ``TestRoute``
+* run requests against the route using ``TestRoute.run(request)`` which will return
+  a ``TestResponse``
+* use the methods of ``TestResponse`` to assert on properties of the response
+
+Example
+-------
+
+To see the testkit in action consider the following simple calculator app service:
+
+.. includecode:: ../../code/docs/http/javadsl/testkit/MyAppService.java
+  :include: simple-app
+
+The app extends from ``HttpApp`` which brings all of the directives into scope. Method ``createRoute``
+needs to be implemented to return the complete route of the app.
+
+Here's how you would test that service:
+
+.. includecode:: ../../code/docs/http/javadsl/testkit/TestkitExampleTest.java
+  :include: simple-app-testing
+
+
+Writing Asserting against the HttpResponse
+------------------------------------------
+
+The testkit supports a fluent DSL to write compact assertions on the response by chaining assertions
+using "dot-syntax". To simplify working with streamed responses the entity of the response is first "strictified", i.e.
+entity data is collected into a single ``ByteString`` and provided the entity is supplied as an ``HttpEntityStrict``. This
+allows to write several assertions against the same entity data which wouldn't (necessarily) be possible for the
+streamed version.
+
+All of the defined assertions provide HTTP specific error messages aiding in diagnosing problems.
+
+Currently, these methods are defined on ``TestResponse`` to assert on the response:
+
+=================================================================== =======================================================================
+Assertion                                        Description
+=================================================================== =======================================================================
+``assertStatusCode(int expectedCode)``                              Asserts that the numeric response status code equals the expected one
+``assertStatusCode(StatusCode expectedCode)``                       Asserts that the response ``StatusCode`` equals the expected one
+``assertMediaType(String expectedType)``                            Asserts that the media type part of the response's content type matches
+                                                                    the given String
+``assertMediaType(MediaType expectedType)``                         Asserts that the media type part of the response's content type matches
+                                                                    the given ``MediaType``
+``assertEntity(String expectedStringContent)``                      Asserts that the entity data interpreted as UTF8 equals the expected
+                                                                    String
+``assertEntityBytes(ByteString expectedBytes)``                     Asserts that the entity data bytes equal the expected ones
+``assertEntityAs(Unmarshaller<T> unmarshaller, expectedValue: T)``  Asserts that the entity data if unmarshalled with the given marshaller
+                                                                    equals the given value
+``assertHeaderExists(HttpHeader expectedHeader)``                   Asserts that the response contains an HttpHeader instance equal to the
+                                                                    expected one
+``assertHeaderKindExists(String expectedHeaderName)``               Asserts that the response contains a header with the expected name
+``assertHeader(String name, String expectedValue)``                 Asserts that the response contains a header with the given name and
+                                                                    value.
+=================================================================== =======================================================================
+
+It's, of course, possible to use any other means of writing assertions by inspecting the properties the response
+manually. As written above, ``TestResponse.entity`` and ``TestResponse.response`` return strict versions of the
+entity data.
+
+Supporting Custom Test Frameworks
+---------------------------------
+
+Adding support for a custom test framework is achieved by creating new superclass analogous to
+``JUnitRouteTest`` for writing tests with the custom test framwork deriving from ``akka.http.javadsl.testkit.RouteTest``
+and implementing its abstract methods. This will allow users of the test framework to use ``testRoute`` and
+to write assertions using the assertion methods defined on ``TestResponse``.