public final class RealJenkinsRule extends Object implements org.junit.rules.TestRule
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:
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).
jenkins.war
to test core changes (there is no “compile-on-save” support for this).
TestExtension
is not available.
LoggerRule
is not available.
BuildWatcher
is not available.
Systems not yet tested:
Timeout
can be used.
ExtensionList.add(Object)
can be used as an alternative to TestExtension
.
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 and Description |
---|
RealJenkinsRule() |
Modifier and Type | Method and Description |
---|---|
RealJenkinsRule |
addPlugins(String... plugins)
Add some plugins to the test classpath.
|
org.junit.runners.model.Statement |
apply(org.junit.runners.model.Statement base,
org.junit.runner.Description description) |
RealJenkinsRule |
extraEnv(String key,
String value)
Set an extra environment variable.
|
File |
getHome()
Obtains the Jenkins home directory.
|
URL |
getUrl()
Like
JenkinsRule.getURL() but does not require Jenkins to have been started yet. |
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. |
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.
|
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. |
public RealJenkinsRule addPlugins(String... plugins)
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.
public RealJenkinsRule omitPlugins(String... plugins)
plugins
- one or more code names, like token-macro
public RealJenkinsRule javaOptions(String... options)
options
- one or more options, like -Dorg.jenkinsci.Something.FLAG=true
public RealJenkinsRule extraEnv(String key, String value)
value
- null to cancel a previously set variablepublic RealJenkinsRule withTimeout(int timeout)
startJenkins()
completes and runRemotely(org.jvnet.hudson.test.RealJenkinsRule.Step)
is ready.
The default is currently set to 600 (10m).timeout
- number of seconds before exiting, or zero to disablepublic RealJenkinsRule withHost(String host)
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).
public RealJenkinsRule withWar(File war)
war/target/jenkins.war
in case of core.public RealJenkinsRule includeTestClasspathPlugins(boolean includeTestClasspathPlugins)
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/javaincludeTestClasspathPlugins
- false if plugins from pom should not be used (default true)public org.junit.runners.model.Statement apply(org.junit.runners.model.Statement base, org.junit.runner.Description description)
apply
in interface org.junit.rules.TestRule
public void then(RealJenkinsRule.Step s) throws Throwable
Throwable
public URL getUrl() throws MalformedURLException
JenkinsRule.getURL()
but does not require Jenkins to have been started yet.MalformedURLException
public File getHome()
LocalData
to populate files.public void runRemotely(RealJenkinsRule.Step s) throws Throwable
Throwable
Copyright © 2004–2022. All rights reserved.