Package org.glassfish.jersey.test

Class JerseyTest

  • Direct Known Subclasses:
    JerseyTestNg
    public abstract class JerseyTest
extends Object
    Parent class for testing JAX-RS and Jersey-based applications using Jersey test framework.

    At construction this class will obtain a test container factory implementation.

    Before each test method in an extending class is run the test container factory is used to obtain a configured test container. Then the TestContainer.start() method is invoked on the configured test container. After each test method has run, the TestContainer.stop() method is invoked on the test container. Stopped test container generally shouldn't be again started for another test, rather a new test container should be created. Every test method in the JerseyTest subclass can invoke the client() to obtain a JAX-RS Client, from which WebTarget instances can be created to send arbitrary requests. Also, one of the target methods (target() or target(String)) may be invoked to obtain a JAX-RS WebTarget instances from which requests can be sent to and responses received from the Web application under test.

    If a test container factory is not explicitly declared using the appropriate constructor (see JerseyTest(TestContainerFactory)) or by overriding the getTestContainerFactory() method, then a default test container factory will be obtained as follows:

    1. If a system property "jersey.config.test.container.factory" is set and the value is a fully qualified class name of a class that extends from TestContainerFactory then the test container factory used by default will be an instance of that class. A TestContainerException will be thrown if the class cannot be loaded or instantiated.
    2. Otherwise, META-INF/services locations on the class path will be scanned for implementation providers of TestContainerFactory SPI. If a single implementation is found, it will be used. If multiple implementations are found, the default "jersey.config.test.container.factory" implementation will be selected if present, otherwise the first found implementation will be selected and a warning message will be logged.
    3. If no TestContainerFactory has been selected in the steps above, Jersey test framework will try to instantiate the default test container factory implementation ( "org.glassfish.jersey.test.grizzly.GrizzlyTestContainerFactory") directly. A TestContainerException will be thrown if this class cannot be loaded or instantiated.

    The test container is configured by a DeploymentContext that is either provided by subclass or automatically created by JerseyTest based on the provided JAX-RS / Jersey Application class or instance to be tested. A TestContainerException will be thrown if the configured test container factory cannot support the deployment context type. Two deployment context are provided:

    1. A basic deployment context, of type DeploymentContext, compatible with all test containers that are not based on Servlet deployment model.
    2. A Servlet-based deployment context, of type ServletDeploymentContext, compatible with Servlet-based test containers.

    Author:
    Paul Sandoz, Srinivas Bhimisetty, Pavel Bucek, Michal Gajdos, Marek Potociar

    • Constructor Detail

      • JerseyTest

        public JerseyTest()
        Initialize JerseyTest instance.

        This constructor can be used from an extending subclass.

        When this constructor is used, the extending concrete subclass must implement one of the configure() or configureDeployment() methods to provide the tested application configuration and deployment context.

      • JerseyTest

        public JerseyTest​(TestContainerFactory testContainerFactory)
        Initialize JerseyTest instance and specify the test container factory to be used by this test.

        This constructor can be used from an extending subclass.

        When this constructor is used, the extending concrete subclass must implement one of the configure() or configureDeployment() methods to provide the tested application configuration and deployment context.

        Parameters:
        testContainerFactory - the test container factory to use for testing.

      • JerseyTest

        public JerseyTest​(Application jaxrsApplication)
        Initialize JerseyTest instance.

        This constructor can be used from an extending subclass.

        When this constructor is used, the extending concrete subclass must implement one of the configure() or configureDeployment() methods are ignored.

        Please note that when this constructor is used, recording of startup logs as well as configuring other JerseyTest properties and features may not work properly. While using this constructor should generally be avoided, in certain scenarios it may be necessary to use this constructor. (E.g. when running parameterized tests in which application is created based on test parameters passed in by JUnit framework via test constructor - in such case it is not possible to propagate the necessary information to one of the overridden JerseyTest.configure... methods).

        Parameters:
        jaxrsApplication - tested application.

    • Method Detail

      • enable

        protected final void enable​(String featureName)
        Programmatically enable a feature with a given name. Enabling of the feature may be overridden via a system property.
        Parameters:
        featureName - name of the enabled feature.

      • disable

        protected final void disable​(String featureName)
        Programmatically disable a feature with a given name. Disabling of the feature may be overridden via a system property.
        Parameters:
        featureName - name of the disabled feature.

      • forceEnable

        protected final void forceEnable​(String featureName)
        Programmatically force-enable a feature with a given name. Force-enabling of the feature cannot be overridden via a system property. Use with care!
        Parameters:
        featureName - name of the force-enabled feature.

      • forceDisable

        protected final void forceDisable​(String featureName)
        Programmatically force-disable a feature with a given name. Force-disabling of the feature cannot be overridden via a system property. Use with care!
        Parameters:
        featureName - name of the force-disabled feature.

      • set

        protected final void set​(String propertyName,
                         Object value)
        Programmatically set a value of a property with a given name. The property value may be overridden via a system property.
        Parameters:
        propertyName - name of the property.
        value - property value.

      • set

        protected final void set​(String propertyName,
                         String value)
        Programmatically set a value of a property with a given name. The property value may be overridden via a system property.
        Parameters:
        propertyName - name of the property.
        value - property value.

      • forceSet

        protected final void forceSet​(String propertyName,
                              String value)
        Programmatically force-set a value of a property with a given name. The force-set property value cannot be overridden via a system property.
        Parameters:
        propertyName - name of the property.
        value - property value.

      • isEnabled

        protected final boolean isEnabled​(String propertyName)
        Check if the Jersey test boolean property (flag) has been set to true.
        Parameters:
        propertyName - name of the Jersey test boolean property.
        Returns:
        true if the test property has been enabled, false otherwise.

      • configure

        protected Application configure()
        Create the tested JAX-RS /Jersey application.

        This method may be overridden by subclasses to provide the configured JAX-RS /Jersey application to be tested. The method may be also used to configure JerseyTest instance properties.

        Unless configureDeployment() method is overridden in the subclass, the configure() method is invoked by configureDeployment() to create default deployment context for the tested application. As such, the method is invoked in the scope of one of the JerseyTest constructors. Default implementation of this method throws UnsupportedOperationException, so that construction of JerseyTest instance fails unless one of the configure() or configureDeployment() methods is overridden in the subclass.

        Note that since the method is invoked from JerseyTest constructor, the overriding implementation of the method must not depend on any subclass fields as those will not be initialized yet when the method is invoked.

        Also note that in case the JerseyTest(jakarta.ws.rs.core.Application) constructor is used, the method is never invoked.

        Returns:
        tested JAX-RS /Jersey application.

      • configureDeployment

        protected DeploymentContext configureDeployment()
        Create and configure deployment context for the tested application.

        This method may be overridden by subclasses to provide custom test container deployment context for the tested application. The method may be also used to configure JerseyTest instance properties.

        The method is invoked from JerseyTest constructors to provide deployment context for the tested application. Default implementation of this method creates new deployment context using JAX-RS application instance obtained by calling the configure() method.

        Note that since the method is invoked from JerseyTest constructor, the overriding implementation of the method must not depend on any subclass fields as those will not be initialized yet when the method is invoked.

        Also note that in case the JerseyTest(jakarta.ws.rs.core.Application) constructor is used, the method is never invoked.

        Returns:
        configured deployment context for the tested application.
        Since:
        2.8

      • getTestContainerFactory

        protected TestContainerFactory getTestContainerFactory()
                                                throws TestContainerException
        Return an instance of TestContainerFactory class.

        This method is used only once during JerseyTest instance construction to retrieve the factory responsible for providing TestContainer that will be used to deploy the tested application.

        A default implementation first searches for the TestContainerFactory set via constructor, then it looks for a TestContainerFactory implementation class name set via "jersey.config.test.container.factory" system property with a fallback to searching for TestContainerFactory service providers on the class path. At last, if no TestContainerFactory has been found, the method attempts to create new default TestContainerFactory implementation instance ("org.glassfish.jersey.test.grizzly.GrizzlyTestContainerFactory").

        Alternatively, this method may be overridden to directly provide a custom TestContainerFactory instance. Note that since the method is invoked from JerseyTest constructor, the overriding implementation of the method must not depend on any subclass fields as those will not be initialized yet when the method is invoked.

        Returns:
        an instance of TestContainerFactory class.
        Throws:
        TestContainerException - if the initialization of TestContainerFactory instance is not successful.

      • getSslContext

        protected Optional<SSLContext> getSslContext()
        Return an optional instance of SSLContext class.

        This method is used only once during JerseyTest instance construction to retrieve the ssl configuration. By default the ssl configuration is absent, to enable it please override this method and getSslParameters()

        Returns:
        an optional instance of SSLContext class.

      • getSslParameters

        protected Optional<SSLParameters> getSslParameters()
        Return an optional instance of SSLParameters class.

        This method is used only once during JerseyTest instance construction to retrieve the ssl configuration. By default the ssl configuration is absent, to enable it please override this method and getSslContext() ()}

        Returns:
        an optional instance of SSLContext class.

      • target

        public final WebTarget target()
        Create a JAX-RS web target whose URI refers to the base URI the tested JAX-RS / Jersey application is deployed at, plus the path specified in the path argument.

        This method is an equivalent of calling client().target(getBaseUri()).

        Returns:
        the created JAX-RS web target.

      • target

        public final WebTarget target​(String path)
        Create a JAX-RS web target whose URI refers to the base URI the tested JAX-RS / Jersey application is deployed at, plus the path specified in the path argument.

        This method is an equivalent of calling target().path(path).

        Parameters:
        path - relative path (from tested application base URI) this web target should point to.
        Returns:
        the created JAX-RS web target.

      • client

        public final Client client()
        Get the JAX-RS test client that is pre-configured for this test.
        Returns:
        the configured test client.

      • setUp

        @BeforeEach
public void setUp()
           throws Exception
        Set up the test by creating a test container instance, starting it and by creating a new pre-configured test client. The test container is obtained from the test container factory.
        Throws:
        TestContainerException - if the default test container factory cannot be obtained, or the test application deployment context is not supported by the test container factory.
        Exception - if an exception is thrown during setting up the test environment.

      • getClient

        protected Client getClient()
        Get the JAX-RS test client that is pre-configured for this test. This method can be overridden.
        Returns:
        the configured test client.

      • setClient

        protected Client setClient​(Client client)
        Get the old JAX-RS test client and set a new one. This method can be overridden.
        Parameters:
        client - the configured test client.
        Returns:
        old configured test client.

      • configureClient

        protected void configureClient​(ClientConfig config)
        Configure the test client.

        The method can be overridden by JerseyTest subclasses to conveniently configure the test client instance used by Jersey test framework (either returned from client() method or used to create WebTarget instances returned from one of the target methods (target() or target(String)).

        Prior to every test method run, a new client instance is configured and created using the client configuration provided by the TestContainer as well as any internal JerseyTest client configuration settings.

        Before the actual client instance creation, Jersey test framework invokes this method in order to allow the subclasses to further customize created client instance.

        After each test method is run, the existing client instance is closed and discarded.

        Default implementation of the method is "no-op".

        Parameters:
        config - Jersey test client configuration that can be modified before the client is created.

      • getBaseUri

        protected URI getBaseUri()
        Returns the base URI of the tested application.
        Returns:
        the base URI of the tested application.

      • getPort

        protected final int getPort()
        Get the port to be used for test application deployments.
        Returns:
        The HTTP port of the URI

      • getAsyncTimeoutMultiplier

        protected int getAsyncTimeoutMultiplier()
        Returns TestProperties.ASYNC_TIMEOUT_MULTIPLIER or 1 if the property is not defined.
        Returns:
        Multiplier of the async timeout for async test.

      • close

        public final void close​(Response... responses)
        Utility method that safely closes a response without throwing an exception.
        Parameters:
        responses - responses to close. Each response may be null.
        Since:
        2.5

      • closeIfNotNull

        public static void closeIfNotNull​(Client... clients)
        Utility method that safely closes a client instance without throwing an exception.
        Parameters:
        clients - client instances to close. Each instance may be null.
        Since:
        2.5