Package ratpack.test.embed

Interface EmbeddedApp

  • All Superinterfaces:
    ApplicationUnderTest, java.lang.AutoCloseable, CloseableApplicationUnderTest
    All Known Implementing Classes:
    MockApi
    public interface EmbeddedApp
extends CloseableApplicationUnderTest
    An application created and used at runtime, useful for functionally testing subsets of functionality.

    This mechanism can be used for functionally testing isolated sections of an application, or for testing general libraries that provide reusable functionality (e.g. Ratpack Guice modules).

    Different implementations expose different API that can be used to define the actual application under test.

    As embedded applications also implement ApplicationUnderTest, they are suitable for use with clients accessing the app via HTTP. Implementations must ensure that the application is up and receiving request when returning from getAddress(). Be sure to close() the application after use to free resources.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default void close()
      Stops the server returned by getServer().
      static EmbeddedApp fromHandler​(ratpack.handling.Handler handler)
      Creates an embedded application with a default launch config (no base dir, ephemeral port) and the given handler.
      static EmbeddedApp fromHandlerFactory​(ratpack.func.Function<? super ratpack.registry.Registry,​? extends ratpack.handling.Handler> handlerFactory)
      Creates an embedded application with a default launch config (no base dir, ephemeral port) and the given handler.
      static EmbeddedApp fromHandlers​(ratpack.func.Action<? super ratpack.handling.Chain> action)
      Creates an embedded application with a default launch config (no base dir, ephemeral port) and the given handler chain.
      static EmbeddedApp fromServer​(ratpack.func.Factory<? extends ratpack.server.RatpackServer> server)
      Creates an embedded application for the given server.
      static EmbeddedApp fromServer​(ratpack.server.RatpackServer server)
      Creates an embedded application for the given server.
      static EmbeddedApp fromServer​(ratpack.server.ServerConfigBuilder serverConfig, ratpack.func.Action<? super ratpack.server.RatpackServerSpec> definition)
      Creates an embedded application using the given server config, and server creating function.
      static EmbeddedApp fromServer​(ratpack.server.ServerConfig serverConfig, ratpack.func.Action<? super ratpack.server.RatpackServerSpec> definition)
      Creates an embedded application using the given server config, and server creating function.
      default java.net.URI getAddress()
      The address of the application under test, which is guaranteed to be listening for requests.
      ratpack.server.RatpackServer getServer()
      The server for the application.
      static EmbeddedApp of​(ratpack.func.Action<? super ratpack.server.RatpackServerSpec> definition)
      Creates an embedded application from the given function.

    • Method Detail

      • fromServer

        static EmbeddedApp fromServer​(ratpack.server.RatpackServer server)
        Creates an embedded application for the given server.
        Parameters:
        server - the server to embed
        Returns:
        a newly created embedded application

      • of

        static EmbeddedApp of​(ratpack.func.Action<? super ratpack.server.RatpackServerSpec> definition)
               throws java.lang.Exception
        Creates an embedded application from the given function.
        Parameters:
        definition - a function that defines the server
        Returns:
        a newly created embedded application
        Throws:
        java.lang.Exception - if an error is encountered creating the application
        See Also:
        RatpackServer.of(Action)

      • fromServer

        static EmbeddedApp fromServer​(ratpack.func.Factory<? extends ratpack.server.RatpackServer> server)
        Creates an embedded application for the given server.
        Parameters:
        server - a factory that creates the server to embed
        Returns:
        a newly created embedded application

      • fromServer

        static EmbeddedApp fromServer​(ratpack.server.ServerConfigBuilder serverConfig,
                              ratpack.func.Action<? super ratpack.server.RatpackServerSpec> definition)
        Creates an embedded application using the given server config, and server creating function.
        Parameters:
        serverConfig - the server configuration
        definition - a function to create the server to embed
        Returns:
        a newly created embedded application

      • fromServer

        static EmbeddedApp fromServer​(ratpack.server.ServerConfig serverConfig,
                              ratpack.func.Action<? super ratpack.server.RatpackServerSpec> definition)
        Creates an embedded application using the given server config, and server creating function.
        Parameters:
        serverConfig - the server configuration
        definition - a function to create the server to embed
        Returns:
        a newly created embedded application

      • fromHandlerFactory

        static EmbeddedApp fromHandlerFactory​(ratpack.func.Function<? super ratpack.registry.Registry,​? extends ratpack.handling.Handler> handlerFactory)
        Creates an embedded application with a default launch config (no base dir, ephemeral port) and the given handler.

        If you need to tweak the server config, use fromServer(ServerConfig, Action).

        Parameters:
        handlerFactory - a handler factory
        Returns:
        a newly created embedded application

      • fromHandler

        static EmbeddedApp fromHandler​(ratpack.handling.Handler handler)
        Creates an embedded application with a default launch config (no base dir, ephemeral port) and the given handler.

        If you need to tweak the server config, use fromServer(ServerConfig, Action).

        Parameters:
        handler - the application handler
        Returns:
        a newly created embedded application

      • fromHandlers

        static EmbeddedApp fromHandlers​(ratpack.func.Action<? super ratpack.handling.Chain> action)
        Creates an embedded application with a default launch config (no base dir, ephemeral port) and the given handler chain.

        If you need to tweak the server config, use fromServer(ServerConfig, Action).

        Parameters:
        action - the handler chain definition
        Returns:
        a newly created embedded application

      • getServer

        ratpack.server.RatpackServer getServer()
        The server for the application.

        Calling this method does not implicitly start the server.

        Returns:
        The server for the application

      • getAddress

        default java.net.URI getAddress()
        The address of the application under test, which is guaranteed to be listening for requests.

        Implementations should start the application if it has not already been started before returning from this method.

        Specified by:
        getAddress in interface ApplicationUnderTest
        Returns:
        the address of the application under test

      • close

        default void close()
        Stops the server returned by getServer().

        Exceptions thrown by calling RatpackServer.stop() are suppressed and written to System.err.

        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface CloseableApplicationUnderTest