Package org.jvnet.hudson.test

Class RealJenkinsRule

  • All Implemented Interfaces:
    org.junit.rules.TestRule
    public final class RealJenkinsRule
extends Object
implements org.junit.rules.TestRule
    Like JenkinsSessionRule but running Jenkins in a more realistic environment.

    Though Jenkins is run in a separate JVM using Winstone (java -jar jenkins.war), you can still do “whitebox” testing: directly calling Java API methods, starting from JenkinsRule or not. This is because the test code gets sent to the remote JVM and loaded and run there. (Thus when using Maven, there are at least three JVMs involved: Maven itself; the Surefire booter with your top-level test code; and the Jenkins controller with test bodies.) Just as with JenkinsRule, all plugins found in the test classpath will be enabled, but with more realistic behavior: class loaders in a graph, pluginFirstClassLoader and maskClasses, etc.

    “Compile-on-save” style development works for classes and resources in the current plugin: with a suitable IDE, you can edit a source file, have it be sent to target/classes/, and rerun a test without needing to go through a full Maven build cycle. This is because target/test-classes/the.hpl is used to load unpacked plugin resources.

    Like JenkinsRule, the controller is started in “development mode”: the setup wizard is suppressed, the update center is not checked, etc.

    Known limitations:

    • Execution is a bit slower due to the overhead of launching a new JVM; and class loading overhead cannot be shared between test cases. More memory is needed.
    • Remote thunks must be serializable. If they need data from the test JVM, you will need to create a static nested class to package that.
    • static state cannot be shared between the top-level test code and test bodies (though the compiler will not catch this mistake).
    • When using a snapshot dep on Jenkins core, you must build jenkins.war to test core changes (there is no “compile-on-save” support for this).
    • Assume is not available.
    • TestExtension is not available.
    • LoggerRule is not available, however additional loggers can be configured via withLogger(Class, Level)}.
    • BuildWatcher is not available, but you can use TailLog instead.

    Systems not yet tested:

    • Possibly Timeout can be used.
    • Possibly ExtensionList.add(Object) can be used as an alternative to TestExtension.

    • Method Detail

      • addPlugins

        public RealJenkinsRule addPlugins​(String... plugins)
        Add some plugins to the test classpath.
        Parameters:
        plugins - Filenames of the plugins to install. These are expected to be absolute test classpath resources, such as plugins/workflow-job.hpi for example.

        Committing that file to SCM (say, src/test/resources/sample.jpi) is reasonable for small fake plugins built for this purpose and exercising some bit of code. If you wish to test with larger archives of real plugins, this is possible for example by binding dependency:copy to the process-test-resources phase.

        In most cases you do not need this method. Simply add whatever plugins you are interested in testing against to your POM in test scope. These, and their transitive dependencies, will be loaded in all RealJenkinsRule tests. This method is useful if only a particular test may load the tested plugin, or if the tested plugin is not available in a repository for use as a test dependency.

      • omitPlugins

        public RealJenkinsRule omitPlugins​(String... plugins)
        Omit some plugins in the test classpath.
        Parameters:
        plugins - one or more code names, like token-macro

      • javaOptions

        public RealJenkinsRule javaOptions​(String... options)
        Add some JVM startup options.
        Parameters:
        options - one or more options, like -Dorg.jenkinsci.Something.FLAG=true

      • jenkinsOptions

        public RealJenkinsRule jenkinsOptions​(String... options)
        Add some Jenkins (including Winstone) startup options. You probably meant to use javaOptions(String...).
        Parameters:
        options - one or more options, like --webroot=/tmp/war --pluginroot=/tmp/plugins

      • extraEnv

        public RealJenkinsRule extraEnv​(String key,
                                String value)
        Set an extra environment variable.
        Parameters:
        value - null to cancel a previously set variable

      • withHost

        public RealJenkinsRule withHost​(String host)
        Sets a custom host name for the Jenkins root URL.

        By default, this is just localhost. But you may wish to set it to something else that resolves to localhost, such as some-id.127.0.0.1.nip.io. This is particularly useful when running multiple copies of Jenkins (and/or other services) in one test case, since browser cookies are sensitive to host but not port and so otherwise HttpServletRequest.getSession(boolean) might accidentally be shared across otherwise distinct services.

        Calling this method does not change the fact that Jenkins will be configured to listen only on localhost for security reasons (so others in the same network cannot access your system under test, especially if it lacks authentication).

      • withWar

        public RealJenkinsRule withWar​(File war)
        Sets a custom WAR file to be used by the rule instead of the one in the path or war/target/jenkins.war in case of core.

      • withJavaHome

        public RealJenkinsRule withJavaHome​(String JavaHome)
        Allows to specify a java home, defaults to JAVA_HOME if not used

      • withName

        public RealJenkinsRule withName​(String name)
        Sets a name for this instance, which will be prefixed to log messages to simplify debugging.

      • getName

        public String getName()

      • withPort

        public RealJenkinsRule withPort​(int port)
        Provides a custom fixed port instead of a random one.
        Parameters:
        port - a custom port to use instead of a random one.

      • withHttpListenAddress

        public RealJenkinsRule withHttpListenAddress​(String httpListenAddress)
        Provides a custom interface to listen to.

        Important: for security reasons this should be overridden only in special scenarios, such as testing inside a Docker container. Otherwise a developer running tests could inadvertently expose a Jenkins service without password protection, allowing remote code execution.

        Parameters:
        httpListenAddress - network interface such as 
        0.0.0.0
        . Defaults to 
        127.0.0.1
        .

      • withDebugPort

        public RealJenkinsRule withDebugPort​(int debugPort)
        Allows usage of a static debug port instead of a random one.

        This allows to use predefined debug configurations in the IDE.

        Typical usage is in a base test class where multiple named controller instances are defined with fixed ports 

         public RealJenkinsRule cc1 = new RealJenkinsRule().withName("cc1").withDebugPort(4001).withDebugServer(false);

 public RealJenkinsRule cc2 = new RealJenkinsRule().withName("cc2").withDebugPort(4002).withDebugServer(false);
        Then have debug configurations in the IDE set for ports
        • 5005 (test VM) - debugger mode "attach to remote vm"
        • 4001 (cc1) - debugger mode "listen to remote vm"
        • 4002 (cc2) - debugger mode "listen to remote vm"

        This allows for debugger to reconnect in scenarios where restarts of controllers are involved.

        Parameters:
        debugPort - the TCP port to use for debugging this Jenkins instance. Between 0 (random) and 65536 (excluded).

      • withDebugServer

        public RealJenkinsRule withDebugServer​(boolean debugServer)
        Allows to use debug in server mode or client mode. Client mode is friendlier to controller restarts.
        Parameters:
        debugServer - true to use server=y, false to use server=n
        See Also:
        withDebugPort(int)

      • withDebugSuspend

        public RealJenkinsRule withDebugSuspend​(boolean debugSuspend)
        Whether to suspend the controller VM on startup until debugger is connected. Defaults to false.
        Parameters:
        debugSuspend - true to suspend the controller VM on startup until debugger is connected.

      • includeTestClasspathPlugins

        public RealJenkinsRule includeTestClasspathPlugins​(boolean includeTestClasspathPlugins)
        The intended use case for this is to use the plugins bundled into the war withWar(File) instead of the plugins in the pom. A typical scenario for this feature is a test which does not live inside a plugin's src/test/java
        Parameters:
        includeTestClasspathPlugins - false if plugins from pom should not be used (default true)

      • prepareHomeLazily

        public RealJenkinsRule prepareHomeLazily​(boolean prepareHomeLazily)
        Allows JENKINS_HOME initialization to be delayed until startJenkins() is called for the first time.

        This allows methods such as addPlugins(java.lang.String...) to be called dynamically inside of test methods, which enables related tests that need to configure RealJenkinsRule in different ways to be defined in the same class using only a single instance of RealJenkinsRule.

      • getJacocoAgentOptions

        public static List<String> getJacocoAgentOptions()

      • apply

        public org.junit.runners.model.Statement apply​(org.junit.runners.model.Statement base,
                                               org.junit.runner.Description description)
        Specified by:
        apply in interface org.junit.rules.TestRule

      • deprovision

        public void deprovision()
                 throws Exception
        Deletes JENKINS_HOME. This method does not need to be invoked when using @Rule or @ClassRule to run RealJenkinsRule.
        Throws:
        Exception

      • isAlive

        public boolean isAlive()
        Returns true if the Jenkins process is alive.

      • getHome

        public File getHome()
        Obtains the Jenkins home directory. Normally it will suffice to use LocalData to populate files.

      • stopJenkins

        public void stopJenkins()
                 throws Throwable
        Stops Jenkins and releases any system resources associated with it. If Jenkins is already stopped then invoking this method has no effect.
        Throws:
        Throwable

      • runRemotely

        public void runRemotely​(RealJenkinsRule.Step... steps)
                 throws Throwable
        Runs one or more steps on the remote system. (Compared to multiple calls, passing a series of steps is slightly more efficient as only one network call is made.)
        Throws:
        Throwable