org.jvnet.hudson.test

Class RealJenkinsRule

java.lang.Object

org.jvnet.hudson.test.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).
• TestExtension is not available.
• LocalData is not available.
• LoggerRule is not available.
• BuildWatcher is not available.
• There is not currently enough flexibility in how the controller is launched (such as custom environment variables).

Systems not yet tested:

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RealJenkinsRule.CustomJenkinsRule
static class	RealJenkinsRule.Endpoint
static class	RealJenkinsRule.Init2
static class	RealJenkinsRule.ProxyException
static interface	RealJenkinsRule.Step One step to run.

Constructor Summary

Constructors

Constructor and Description
RealJenkinsRule()

Method Summary

Modifier and Type	Method and Description
org.junit.runners.model.Statement	apply(org.junit.runners.model.Statement base, org.junit.runner.Description description)
URL	getUrl() Like JenkinsRule.getURL() but does not require Jenkins to have been started yet.
RealJenkinsRule	javaOptions(String... options) Add some JVM startup options.
RealJenkinsRule	omitPlugins(String... plugins) Omit some plugins in the test classpath.
void	runRemotely(RealJenkinsRule.Step s)
void	startJenkins()
void	stopJenkins()
void	then(RealJenkinsRule.Step s) Run one Jenkins session, send a test thunk, and shut down.
RealJenkinsRule	withHost(String host) Sets a custom host name for the Jenkins root URL.
RealJenkinsRule	withTimeout(int timeout) Adjusts the test timeout.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RealJenkinsRule

public RealJenkinsRule()

Method Detail

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

withTimeout

public RealJenkinsRule withTimeout(int timeout)

Adjusts the test timeout. The timer starts when startJenkins() completes and runRemotely(org.jvnet.hudson.test.RealJenkinsRule.Step) is ready. The default is currently set to 600 (10m).

Parameters:

timeout - number of seconds before exiting, or zero to disable

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).

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

then

public void then(RealJenkinsRule.Step s)
          throws Throwable

Run one Jenkins session, send a test thunk, and shut down.

Throws:

Throwable

getUrl

public URL getUrl()
           throws MalformedURLException

Like JenkinsRule.getURL() but does not require Jenkins to have been started yet.

Throws:

MalformedURLException

startJenkins

public void startJenkins()
                  throws Throwable

Throws:

Throwable

stopJenkins

public void stopJenkins()
                 throws Throwable

Throws:

Throwable

runRemotely

public void runRemotely(RealJenkinsRule.Step s)
                 throws Throwable

Throws:

Throwable