org.jvnet.hudson.test

Class JenkinsRule

java.lang.Object

org.jvnet.hudson.test.JenkinsRule

All Implemented Interfaces:

hudson.ExtensionPoint, hudson.model.Action, hudson.model.ModelObject, hudson.model.RootAction, org.junit.rules.MethodRule, org.junit.rules.TestRule

Direct Known Subclasses:

GroovyJenkinsRule, NodeProvisionerRule

public class JenkinsRule
extends Object
implements org.junit.rules.TestRule, org.junit.rules.MethodRule, hudson.model.RootAction

JUnit rule to allow test cases to fire up a Jenkins instance.

Since:

1.436

Author:

Stephen Connolly

See Also:

Wiki article about unit testing in Jenkins, RestartableJenkinsRule

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JenkinsRule.BreakException
static class	JenkinsRule.DummySecurityRealm
static class	JenkinsRule.JSONWebResponse Convenience wrapper for JSON responses.
static class	JenkinsRule.TestBuildWrapper
class	JenkinsRule.WebClient Extends WebClient and provide convenience methods for accessing Hudson.

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

hudson.ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field and Description
JenkinsComputerConnectorTester	computerConnectorTester
String	contextPath Where in the Server is Jenkins deployed?
protected TestEnvironment	env
protected HudsonHomeLoader	homeLoader
hudson.model.Hudson	hudson Deprecated.
jenkins.model.Jenkins	jenkins
protected JavaScriptDebugger	jsDebugger JavaScript "debugger" that provides you information about the JavaScript call stack and the current values of the local variables in those stack frame.
protected int	localPort TCP/IP port that the server is listening on.
static org.eclipse.jetty.http.MimeTypes	MIME_TYPES
static List<hudson.tools.ToolProperty<?>>	NO_PROPERTIES
protected List<JenkinsRecipe.Runner>	recipes
protected org.eclipse.jetty.server.Server	server
static int	SLAVE_DEBUG_PORT Specify this to a TCP/IP port number to have slaves started with the debugger.
protected List<LenientRunnable>	tearDowns Runnables to be invoked at after() .
protected org.junit.runner.Description	testDescription
int	timeout Number of seconds until the test times out.
boolean	useLocalPluginManager Deprecated. Use pluginManager

Constructor Summary

Constructors

Constructor and Description
JenkinsRule()

Method Summary

Modifier and Type	Method and Description
static void	_configureJenkinsForTest(jenkins.model.Jenkins jenkins) Configures a Jenkins instance for test.
static void	_configureUpdateCenter(jenkins.model.Jenkins jenkins) Internal method used to configure update center to avoid network traffic.
static org.eclipse.jetty.security.LoginService	_configureUserRealm() Creates a HashLoginService with three users: alice, bob and charlie The password is same as the username
static org.apache.commons.lang3.tuple.ImmutablePair<org.eclipse.jetty.server.Server,javax.servlet.ServletContext>	_createWebServer(String contextPath, Consumer<Integer> portSetter, ClassLoader classLoader, int localPort, Supplier<org.eclipse.jetty.security.LoginService> loginServiceSupplier) Creates a web server on which Jenkins can run
static org.apache.commons.lang3.tuple.ImmutablePair<org.eclipse.jetty.server.Server,javax.servlet.ServletContext>	_createWebServer(String contextPath, Consumer<Integer> portSetter, ClassLoader classLoader, int localPort, Supplier<org.eclipse.jetty.security.LoginService> loginServiceSupplier, BiConsumer<org.eclipse.jetty.webapp.WebAppContext,org.eclipse.jetty.server.Server> contextAndServerConsumer) Creates a web server on which Jenkins can run
static void	_stopJenkins(org.eclipse.jetty.server.Server server, List<LenientRunnable> tearDowns, jenkins.model.Jenkins jenkins) Internal method to stop Jenkins instance.
void	after() Override to tear down your specific external resource.
org.junit.runners.model.Statement	apply(org.junit.runners.model.Statement base, org.junit.runner.Description description)
org.junit.runners.model.Statement	apply(org.junit.runners.model.Statement base, org.junit.runners.model.FrameworkMethod method, Object target) Backward compatibility with JUnit 4.8.
void	assertAllImageLoadSuccessfully(com.gargoylesoftware.htmlunit.html.HtmlPage p) Makes sure that all the images in the page loads successfully.
<R extends hudson.model.Run> R	assertBuildStatus(hudson.model.Result status, Future<? extends R> r)
<R extends hudson.model.Run> R	assertBuildStatus(hudson.model.Result status, R r) Asserts that the outcome of the build is a specific outcome.
<R extends hudson.model.Run> R	assertBuildStatusSuccess(Future<? extends R> r)
<R extends hudson.model.Run> R	assertBuildStatusSuccess(R r)
void	assertEqualBeans(Object lhs, Object rhs, String properties) Asserts that two JavaBeans are equal as far as the given list of properties are concerned.
void	assertEqualDataBoundBeans(List<?> lhs, List<?> rhs) Makes sure that two collections are identical via assertEqualDataBoundBeans(Object, Object)
void	assertEqualDataBoundBeans(Object lhs, Object rhs) Works like assertEqualBeans(Object, Object, String) but figure out the properties via DataBoundConstructor and DataBoundSetter
void	assertGoodStatus(com.gargoylesoftware.htmlunit.Page page) Assert that the specified page can be served with a "good" HTTP status, eg, the page is not missing and can be served without a server error
void	assertHelpExists(Class<? extends hudson.model.Describable> type, String properties) Asserts that help files exist for the specified properties of the given instance.
void	assertLogContains(String substring, hudson.model.Run run) Asserts that the console output of the build contains the given substring.
void	assertLogNotContains(String substring, hudson.model.Run run) Asserts that the console output of the build does not contain the given substring.
void	assertStringContains(String haystack, String needle)
void	assertStringContains(String message, String haystack, String needle)
void	assertXPath(com.gargoylesoftware.htmlunit.html.DomNode page, String xpath) Asserts that the XPath matches the contents of a DomNode page.
void	assertXPath(com.gargoylesoftware.htmlunit.html.HtmlPage page, String xpath) Asserts that the XPath matches.
void	assertXPathResultsContainText(com.gargoylesoftware.htmlunit.html.DomNode page, String xpath, String needle)
void	assertXPathValue(com.gargoylesoftware.htmlunit.html.DomNode page, String xpath, String expectedValue)
void	assertXPathValueContains(com.gargoylesoftware.htmlunit.html.DomNode page, String xpath, String needle)
void	before() Override to set up your specific external resource.
<J extends hudson.model.Job<J,R> & jenkins.model.ParameterizedJobMixIn.ParameterizedJob<J,R>,R extends hudson.model.Run<J,R> & hudson.model.Queue.Executable> R	buildAndAssertStatus(hudson.model.Result status, J job) Runs specified job and asserts that in finished with given build result.
hudson.model.FreeStyleBuild	buildAndAssertSuccess(hudson.model.FreeStyleProject job) Avoids need for cumbersome this.<J,R>buildAndAssertSuccess(...) type hints under JDK 7 javac (and supposedly also IntelliJ).
<J extends hudson.model.Job<J,R> & jenkins.model.ParameterizedJobMixIn.ParameterizedJob<J,R>,R extends hudson.model.Run<J,R> & hudson.model.Queue.Executable> R	buildAndAssertSuccess(J job)
void	configRoundtrip() Hits the Hudson system configuration and submits without any modification.
<B extends hudson.tasks.Builder> B	configRoundtrip(B before) Performs a configuration round-trip testing for a builder.
<C extends hudson.slaves.ComputerConnector> C	configRoundtrip(C before)
<N extends hudson.model.Node> N	configRoundtrip(N node)
<P extends hudson.model.Item> P	configRoundtrip(P job) Loads a configuration page and submits it without any modifications, to perform a round-trip configuration test.
<P extends hudson.tasks.Publisher> P	configRoundtrip(P before) Performs a configuration round-trip testing for a publisher.
hudson.model.User	configRoundtrip(hudson.model.User u)
<V extends hudson.model.View> V	configRoundtrip(V view)
protected void	configureUpdateCenter() Configures the update center setting for the test.
protected org.eclipse.jetty.security.LoginService	configureUserRealm() Configures a security realm for a test.
hudson.slaves.ComputerLauncher	createComputerLauncher(hudson.EnvVars env) Creates a launcher for starting a local agent.
JenkinsRule.DummySecurityRealm	createDummySecurityRealm() Creates a test SecurityRealm that recognizes username==password as valid.
MockFolder	createFolder(String name) Creates a simple folder that other jobs can be placed in.
hudson.model.FreeStyleProject	createFreeStyleProject()
hudson.model.FreeStyleProject	createFreeStyleProject(String name)
hudson.Launcher.LocalLauncher	createLocalLauncher() Creates Launcher.LocalLauncher.
hudson.slaves.DumbSlave	createOnlineSlave() Create a new slave on the local host and wait for it to come online before returning.
hudson.slaves.DumbSlave	createOnlineSlave(hudson.model.Label l) Create a new slave on the local host and wait for it to come online before returning.
hudson.slaves.DumbSlave	createOnlineSlave(hudson.model.Label l, hudson.EnvVars env) Create a new slave on the local host and wait for it to come online before returning
PretendSlave	createPretendSlave(FakeLauncher faker)
<T extends hudson.model.TopLevelItem> T	createProject(Class<T> type) Creates a new job with an unique name.
<T extends hudson.model.TopLevelItem> T	createProject(Class<T> type, String name) Creates a new job.
hudson.slaves.DumbSlave	createSlave()
hudson.slaves.DumbSlave	createSlave(boolean waitForChannelConnect)
hudson.slaves.DumbSlave	createSlave(hudson.EnvVars env)
hudson.slaves.DumbSlave	createSlave(hudson.model.Label l) Creates and launches a new slave on the local host.
hudson.slaves.DumbSlave	createSlave(hudson.model.Label l, hudson.EnvVars env)
hudson.slaves.DumbSlave	createSlave(String labels, hudson.EnvVars env) Creates a slave with certain additional environment variables
hudson.slaves.DumbSlave	createSlave(String nodeName, String labels, hudson.EnvVars env)
hudson.model.TaskListener	createTaskListener() Creates a TaskListener connected to stdout.
File	createTmpDir() Deprecated. Use TemporaryFolder instead.
protected String	createUniqueProjectName()
JenkinsRule.WebClient	createWebClient() This is to assist Groovy test clients who are incapable of instantiating the inner classes properly.
protected javax.servlet.ServletContext	createWebServer() Prepares a webapp hosting environment to get ServletContext implementation that we need for testing.
protected javax.servlet.ServletContext	createWebServer(BiConsumer<org.eclipse.jetty.webapp.WebAppContext,org.eclipse.jetty.server.Server> contextAndServerConsumer) Prepares a webapp hosting environment to get ServletContext implementation that we need for testing.
void	disconnectSlave(hudson.slaves.DumbSlave slave)
<V> V	executeOnServer(Callable<V> c) Executes the given closure on the server, by the servlet request handling thread, in the context of an HTTP request.
Constructor<?>	findDataBoundConstructor(Class<?> c)
com.gargoylesoftware.htmlunit.html.HtmlInput	findPreviousInputElement(com.gargoylesoftware.htmlunit.html.HtmlElement current, String name)
<T extends hudson.model.Descriptor<?>> T	get(Class<T> d) Gets the descriptor instance of the current Hudson by its type.
com.gargoylesoftware.htmlunit.html.HtmlButton	getButtonByCaption(com.gargoylesoftware.htmlunit.html.HtmlForm f, String s)
String	getDisplayName()
String	getIconFileName()
jenkins.model.Jenkins	getInstance()
JenkinsRule.JSONWebResponse	getJSON(String path) Get JSON from A Jenkins endpoint.
static String	getLog(hudson.model.Run run) Get entire log file as plain text.
hudson.PluginManager	getPluginManager()
org.junit.runner.Description	getTestDescription()
URL	getURL() Returns the URL of the webapp top page.
String	getUrlName()
File	getWebAppRoot()
void	interactiveBreak() Blocks until the ENTER key is hit.
boolean	isGoodHttpStatus(int status) Determines whether the specified HTTP status code is generally "good"
boolean	isSomethingHappening() Returns true if Hudson is building something or going to build something.
<T> T	last(List<T> items) Returns the last item in the list.
protected hudson.model.Hudson	newHudson() Creates a new instance of Jenkins.
void	pause() Pauses the execution until ENTER is hit in the console.
JenkinsRule.JSONWebResponse	postJSON(String path, Object json) POST a JSON payload to a URL on the underlying Jenkins instance.
void	recipe() Called during the before() to give a test case an opportunity to control the test environment in which Hudson is run.
void	recipeLoadCurrentPlugin() If this test harness is launched for a Jenkins plugin, locate the target/test-classes/the.jpl and add a recipe to install that to the new Jenkins.
com.gargoylesoftware.htmlunit.Page	search(String q) Performs a search from the search box.
void	setPluginManager(hudson.PluginManager pluginManager) Sets the PluginManager to be used when creating a new Jenkins instance.
void	setQuietPeriod(int qp)
void	showAgentLogs(hudson.model.Slave s, LoggerRule loggerRule) Same as showAgentLogs(Slave, Map) but taking a preconfigured list of loggers as a convenience.
void	showAgentLogs(hudson.model.Slave s, Map<String,Level> loggers) Forward agent logs to standard error of the test process.
com.gargoylesoftware.htmlunit.html.HtmlPage	submit(com.gargoylesoftware.htmlunit.html.HtmlForm form) Submits the form.
com.gargoylesoftware.htmlunit.html.HtmlPage	submit(com.gargoylesoftware.htmlunit.html.HtmlForm form, String name) Submits the form by clicking the submit button of the given name.
<R extends hudson.model.Run<?,?>> R	waitForCompletion(R r) Waits for a build to complete.
<R extends hudson.model.Run<?,?>> R	waitForMessage(String message, R r) Waits for a build log to contain a specified string.
void	waitOnline(hudson.model.Slave s) Waits for a newly created slave to come online.
void	waitUntilNoActivity() Waits until Hudson finishes building everything, including those in the queue.
void	waitUntilNoActivityUpTo(int timeout) Waits until Hudson finishes building everything, including those in the queue, or fail the test if the specified timeout milliseconds is
JenkinsRule	with(HudsonHomeLoader homeLoader)
JenkinsRule	with(hudson.PluginManager pluginManager)
JenkinsRule	withExistingHome(File source)
JenkinsRule	withNewHome()
JenkinsRule	withPresetData(String name) Declares that this test case expects to start with one of the preset data sets.

Methods inherited from class java.lang.Object

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

Field Detail

env

protected TestEnvironment env

testDescription

protected org.junit.runner.Description testDescription

hudson

@Deprecated
public hudson.model.Hudson hudson

Deprecated.

Points to the same object as jenkins does.

jenkins

public jenkins.model.Jenkins jenkins

homeLoader

protected HudsonHomeLoader homeLoader

localPort

protected int localPort

TCP/IP port that the server is listening on.

server

protected org.eclipse.jetty.server.Server server

contextPath

public String contextPath

Where in the Server is Jenkins deployed?

Just like ServletContext.getContextPath(), starts with '/' but doesn't end with '/'. Unlike JenkinsRule.WebClient.getContextPath() this is not a complete URL.

tearDowns

protected List<LenientRunnable> tearDowns

Runnables to be invoked at after() .

recipes

protected List<JenkinsRecipe.Runner> recipes

jsDebugger

protected JavaScriptDebugger jsDebugger

JavaScript "debugger" that provides you information about the JavaScript call stack and the current values of the local variables in those stack frame.

Unlike Java debugger, which you as a human interfaces directly and interactively, this JavaScript debugger is to be interfaced by your program (or through the expression evaluation capability of your Java debugger.)

useLocalPluginManager

public boolean useLocalPluginManager

Deprecated. Use pluginManager

If this test case has additional WithPlugin annotations, set to true. This will cause a fresh PluginManager to be created for this test. Leaving this to false enables the test harness to use a pre-loaded plugin manager, which runs faster.

timeout

public int timeout

Number of seconds until the test times out.

computerConnectorTester

public JenkinsComputerConnectorTester computerConnectorTester

NO_PROPERTIES

public static final List<hudson.tools.ToolProperty<?>> NO_PROPERTIES

SLAVE_DEBUG_PORT

public static final int SLAVE_DEBUG_PORT

Specify this to a TCP/IP port number to have slaves started with the debugger.

MIME_TYPES

public static final org.eclipse.jetty.http.MimeTypes MIME_TYPES

Constructor Detail

JenkinsRule

public JenkinsRule()

Method Detail

getInstance

public jenkins.model.Jenkins getInstance()

before

public void before()
            throws Throwable

Override to set up your specific external resource.

Throws:

Throwable - if setup fails (which will disable after

_configureJenkinsForTest

public static void _configureJenkinsForTest(jenkins.model.Jenkins jenkins)
                                     throws Exception

Configures a Jenkins instance for test.

Parameters:

jenkins - jenkins instance which has to be configured

Throws:

Exception - if unable to configure

Since:

2.50

configureUpdateCenter

protected void configureUpdateCenter()
                              throws Exception

Configures the update center setting for the test. By default, we load updates from local proxy to avoid network traffic as much as possible.

Throws:

Exception

_configureUpdateCenter

public static void _configureUpdateCenter(jenkins.model.Jenkins jenkins)
                                   throws Exception

Internal method used to configure update center to avoid network traffic.

Parameters:

jenkins - the Jenkins to configure

Throws:

Exception

Since:

2.50

after

public void after()
           throws Exception

Override to tear down your specific external resource.

Throws:

Exception

_stopJenkins

public static void _stopJenkins(org.eclipse.jetty.server.Server server,
                                List<LenientRunnable> tearDowns,
                                jenkins.model.Jenkins jenkins)

Internal method to stop Jenkins instance.

Parameters:

server - server on which Jenkins is running.

tearDowns - tear down methods for tests

jenkins - the jenkins instance

Since:

2.50

apply

public org.junit.runners.model.Statement apply(org.junit.runners.model.Statement base,
                                               org.junit.runners.model.FrameworkMethod method,
                                               Object target)

Backward compatibility with JUnit 4.8.

Specified by:

apply in interface org.junit.rules.MethodRule

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

getIconFileName

public String getIconFileName()

Specified by:

getIconFileName in interface hudson.model.Action

getDisplayName

public String getDisplayName()

Specified by:

getDisplayName in interface hudson.model.Action

Specified by:

getDisplayName in interface hudson.model.ModelObject

getUrlName

public String getUrlName()

Specified by:

getUrlName in interface hudson.model.Action

newHudson

protected hudson.model.Hudson newHudson()
                                 throws Exception

Creates a new instance of Jenkins. If the derived class wants to create it in a different way, you can override it.

Throws:

Exception

getPluginManager

public hudson.PluginManager getPluginManager()

setPluginManager

public void setPluginManager(hudson.PluginManager pluginManager)

Sets the PluginManager to be used when creating a new Jenkins instance.

Parameters:

pluginManager - null to let Jenkins create a new instance of default plugin manager, like it normally does when running as a webapp outside the test.

with

public JenkinsRule with(hudson.PluginManager pluginManager)

getWebAppRoot

public File getWebAppRoot()
                   throws Exception

Throws:

Exception

createWebServer

protected javax.servlet.ServletContext createWebServer()
                                                throws Exception

Prepares a webapp hosting environment to get ServletContext implementation that we need for testing.

Throws:

Exception

createWebServer

protected javax.servlet.ServletContext createWebServer(@CheckForNull
                                                       BiConsumer<org.eclipse.jetty.webapp.WebAppContext,org.eclipse.jetty.server.Server> contextAndServerConsumer)
                                                throws Exception

Prepares a webapp hosting environment to get ServletContext implementation that we need for testing.

Parameters:

contextAndServerConsumer - configures the WebAppContext and the Server for the instance, before they are started

Throws:

Exception

Since:

2.63

_createWebServer

public static org.apache.commons.lang3.tuple.ImmutablePair<org.eclipse.jetty.server.Server,javax.servlet.ServletContext> _createWebServer(String contextPath,
                                                                                                                                          Consumer<Integer> portSetter,
                                                                                                                                          ClassLoader classLoader,
                                                                                                                                          int localPort,
                                                                                                                                          Supplier<org.eclipse.jetty.security.LoginService> loginServiceSupplier)
                                                                                                                                   throws Exception

Creates a web server on which Jenkins can run

Parameters:

contextPath - the context path at which to put Jenkins

portSetter - the port on which the server runs will be set using this function

classLoader - the class loader for the WebAppContext

localPort - port on which the server runs

loginServiceSupplier - configures the LoginService for the instance

Returns:

ImmutablePair consisting of the Server and the ServletContext

Throws:

Exception

Since:

2.50

_createWebServer

public static org.apache.commons.lang3.tuple.ImmutablePair<org.eclipse.jetty.server.Server,javax.servlet.ServletContext> _createWebServer(String contextPath,
                                                                                                                                          Consumer<Integer> portSetter,
                                                                                                                                          ClassLoader classLoader,
                                                                                                                                          int localPort,
                                                                                                                                          Supplier<org.eclipse.jetty.security.LoginService> loginServiceSupplier,
                                                                                                                                          @CheckForNull
                                                                                                                                          BiConsumer<org.eclipse.jetty.webapp.WebAppContext,org.eclipse.jetty.server.Server> contextAndServerConsumer)
                                                                                                                                   throws Exception

Creates a web server on which Jenkins can run

Parameters:

contextPath - the context path at which to put Jenkins

portSetter - the port on which the server runs will be set using this function

classLoader - the class loader for the WebAppContext

localPort - port on which the server runs

loginServiceSupplier - configures the LoginService for the instance

contextAndServerConsumer - configures the WebAppContext and the Server for the instance, before they are started

Returns:

ImmutablePair consisting of the Server and the ServletContext

Throws:

Exception

Since:

2.50

configureUserRealm

protected org.eclipse.jetty.security.LoginService configureUserRealm()

Configures a security realm for a test.

_configureUserRealm

public static org.eclipse.jetty.security.LoginService _configureUserRealm()

Creates a HashLoginService with three users: alice, bob and charlie The password is same as the username

Returns:

a new login service

Since:

2.50

createProject

public <T extends hudson.model.TopLevelItem> T createProject(Class<T> type,
                                                             String name)
                                                      throws IOException

Creates a new job.

Parameters:

type - Top level item type.

name - Item name.

Throws:

IllegalArgumentException - if the project of the given name already exists.

IOException

createProject

public <T extends hudson.model.TopLevelItem> T createProject(Class<T> type)
                                                      throws IOException

Creates a new job with an unique name.

Parameters:

type - Top level item type.

Throws:

IOException

createFreeStyleProject

public hudson.model.FreeStyleProject createFreeStyleProject()
                                                     throws IOException

Throws:

IOException

createFreeStyleProject

public hudson.model.FreeStyleProject createFreeStyleProject(String name)
                                                     throws IOException

Throws:

IOException

createFolder

public MockFolder createFolder(String name)
                        throws IOException

Creates a simple folder that other jobs can be placed in.

Throws:

IOException

Since:

1.494

createUniqueProjectName

protected String createUniqueProjectName()

createLocalLauncher

public hudson.Launcher.LocalLauncher createLocalLauncher()

Creates Launcher.LocalLauncher. Useful for launching processes.

createTmpDir

@Deprecated
public File createTmpDir()
                              throws IOException

Deprecated. Use TemporaryFolder instead.

Allocates a new temporary directory for the duration of this test.

Throws:

IOException

createSlave

public hudson.slaves.DumbSlave createSlave(boolean waitForChannelConnect)
                                    throws Exception

Throws:

Exception

disconnectSlave

public void disconnectSlave(hudson.slaves.DumbSlave slave)
                     throws Exception

Throws:

Exception

createSlave

public hudson.slaves.DumbSlave createSlave()
                                    throws Exception

Throws:

Exception

createSlave

public hudson.slaves.DumbSlave createSlave(hudson.model.Label l)
                                    throws Exception

Creates and launches a new slave on the local host.

Throws:

Exception

createDummySecurityRealm

public JenkinsRule.DummySecurityRealm createDummySecurityRealm()

Creates a test SecurityRealm that recognizes username==password as valid.

See Also:

MockAuthorizationStrategy

getURL

public URL getURL()
           throws IOException

Returns the URL of the webapp top page. URL ends with '/'.

Throws:

IOException

createSlave

public hudson.slaves.DumbSlave createSlave(hudson.EnvVars env)
                                    throws Exception

Throws:

Exception

createSlave

public hudson.slaves.DumbSlave createSlave(hudson.model.Label l,
                                           hudson.EnvVars env)
                                    throws Exception

Throws:

Exception

createSlave

public hudson.slaves.DumbSlave createSlave(String labels,
                                           hudson.EnvVars env)
                                    throws Exception

Creates a slave with certain additional environment variables

Throws:

Exception

createSlave

public hudson.slaves.DumbSlave createSlave(String nodeName,
                                           String labels,
                                           hudson.EnvVars env)
                                    throws Exception

Throws:

Exception

createPretendSlave

public PretendSlave createPretendSlave(FakeLauncher faker)
                                throws Exception

Throws:

Exception

createComputerLauncher

public hudson.slaves.ComputerLauncher createComputerLauncher(hudson.EnvVars env)
                                                      throws URISyntaxException,
                                                             IOException

Creates a launcher for starting a local agent.

Parameters:

env - Environment variables to add to the slave process. Can be null.

Throws:

URISyntaxException

IOException

createOnlineSlave

public hudson.slaves.DumbSlave createOnlineSlave()
                                          throws Exception

Create a new slave on the local host and wait for it to come online before returning.

Throws:

Exception

createOnlineSlave

public hudson.slaves.DumbSlave createOnlineSlave(hudson.model.Label l)
                                          throws Exception

Create a new slave on the local host and wait for it to come online before returning.

Throws:

Exception

createOnlineSlave

public hudson.slaves.DumbSlave createOnlineSlave(hudson.model.Label l,
                                                 hudson.EnvVars env)
                                          throws Exception

Create a new slave on the local host and wait for it to come online before returning

Throws:

Exception

See Also:

waitOnline(hudson.model.Slave)

waitOnline

public void waitOnline(hudson.model.Slave s)
                throws Exception

Waits for a newly created slave to come online.

Throws:

Exception

See Also:

createSlave()

showAgentLogs

public void showAgentLogs(hudson.model.Slave s,
                          LoggerRule loggerRule)
                   throws Exception

Same as showAgentLogs(Slave, Map) but taking a preconfigured list of loggers as a convenience.

Throws:

Exception

showAgentLogs

public void showAgentLogs(hudson.model.Slave s,
                          Map<String,Level> loggers)
                   throws Exception

Forward agent logs to standard error of the test process. Otherwise log messages would be sent only to Computer.getLogText() etc., or discarded entirely (if below Level.INFO).

Parameters:

s - an online agent

loggers - Logger.getName() tied to log level

Throws:

Exception

interactiveBreak

public void interactiveBreak()
                      throws Exception

Blocks until the ENTER key is hit. This is useful during debugging a test so that one can inspect the state of Hudson through the web browser.

Throws:

Exception

last

public <T> T last(List<T> items)

Returns the last item in the list.

pause

public void pause()
           throws IOException

Pauses the execution until ENTER is hit in the console.

This is often very useful so that you can interact with Hudson from an browser, while developing a test case.

Throws:

IOException

search

public com.gargoylesoftware.htmlunit.Page search(String q)
                                          throws Exception

Performs a search from the search box.

Throws:

Exception

getJSON

public JenkinsRule.JSONWebResponse getJSON(@Nonnull
                                           String path)
                                    throws IOException

Get JSON from A Jenkins endpoint.

Parameters:

path - The endpoint URL.

Returns:

The JSON.

Throws:

IOException

postJSON

public JenkinsRule.JSONWebResponse postJSON(@Nonnull
                                            String path,
                                            @Nonnull
                                            Object json)
                                     throws IOException,
                                            SAXException

POST a JSON payload to a URL on the underlying Jenkins instance.

Parameters:

path - The url path on Jenkins.

json - An object that produces a JSON string from it's toString method.

Returns:

A JSON response.

Throws:

IOException

SAXException

configRoundtrip

public void configRoundtrip()
                     throws Exception

Hits the Hudson system configuration and submits without any modification.

Throws:

Exception

configRoundtrip

public <P extends hudson.model.Item> P configRoundtrip(P job)
                                                throws Exception

Loads a configuration page and submits it without any modifications, to perform a round-trip configuration test.

See http://wiki.jenkins-ci.org/display/JENKINS/Unit+Test#UnitTest-Configurationroundtriptesting

Throws:

Exception

configRoundtrip

public <B extends hudson.tasks.Builder> B configRoundtrip(B before)
                                                   throws Exception

Performs a configuration round-trip testing for a builder.

Throws:

Exception

configRoundtrip

public <P extends hudson.tasks.Publisher> P configRoundtrip(P before)
                                                     throws Exception

Performs a configuration round-trip testing for a publisher.

Throws:

Exception

configRoundtrip

public <C extends hudson.slaves.ComputerConnector> C configRoundtrip(C before)
                                                              throws Exception

Throws:

Exception

configRoundtrip

public hudson.model.User configRoundtrip(hudson.model.User u)
                                  throws Exception

Throws:

Exception

configRoundtrip

public <N extends hudson.model.Node> N configRoundtrip(N node)
                                                throws Exception

Throws:

Exception

configRoundtrip

public <V extends hudson.model.View> V configRoundtrip(V view)
                                                throws Exception

Throws:

Exception

assertBuildStatus

public <R extends hudson.model.Run> R assertBuildStatus(hudson.model.Result status,
                                                        R r)
                                                 throws Exception

Asserts that the outcome of the build is a specific outcome.

Throws:

Exception

assertBuildStatus

public <R extends hudson.model.Run> R assertBuildStatus(hudson.model.Result status,
                                                        Future<? extends R> r)
                                                 throws Exception

Throws:

Exception

isGoodHttpStatus

public boolean isGoodHttpStatus(int status)

Determines whether the specified HTTP status code is generally "good"

assertGoodStatus

public void assertGoodStatus(com.gargoylesoftware.htmlunit.Page page)

Assert that the specified page can be served with a "good" HTTP status, eg, the page is not missing and can be served without a server error

Parameters:

page -

assertBuildStatusSuccess

public <R extends hudson.model.Run> R assertBuildStatusSuccess(R r)
                                                        throws Exception

Throws:

Exception

assertBuildStatusSuccess

public <R extends hudson.model.Run> R assertBuildStatusSuccess(Future<? extends R> r)
                                                        throws Exception

Throws:

Exception

buildAndAssertSuccess

@Nonnull
public <J extends hudson.model.Job<J,R> & jenkins.model.ParameterizedJobMixIn.ParameterizedJob<J,R>,R extends hudson.model.Run<J,R> & hudson.model.Queue.Executable> R buildAndAssertSuccess(@Nonnull
                                                                                                                                                                                                      J job)
                                                                                                                                                                                               throws Exception

Throws:

Exception

buildAndAssertStatus

@Nonnull
public <J extends hudson.model.Job<J,R> & jenkins.model.ParameterizedJobMixIn.ParameterizedJob<J,R>,R extends hudson.model.Run<J,R> & hudson.model.Queue.Executable> R buildAndAssertStatus(@Nonnull
                                                                                                                                                                                                     hudson.model.Result status,
                                                                                                                                                                                                     @Nonnull
                                                                                                                                                                                                     J job)
                                                                                                                                                                                              throws Exception

Runs specified job and asserts that in finished with given build result.

Throws:

Exception

Since:

TODO

buildAndAssertSuccess

@Nonnull
public hudson.model.FreeStyleBuild buildAndAssertSuccess(@Nonnull
                                                                  hudson.model.FreeStyleProject job)
                                                           throws Exception

Avoids need for cumbersome this.<J,R>buildAndAssertSuccess(...) type hints under JDK 7 javac (and supposedly also IntelliJ).

Throws:

Exception

assertLogContains

public void assertLogContains(String substring,
                              hudson.model.Run run)
                       throws IOException

Asserts that the console output of the build contains the given substring.

Throws:

IOException

assertLogNotContains

public void assertLogNotContains(String substring,
                                 hudson.model.Run run)
                          throws IOException

Asserts that the console output of the build does not contain the given substring.

Throws:

IOException

getLog

public static String getLog(hudson.model.Run run)
                     throws IOException

Get entire log file as plain text. Run.getLog() is deprecated for reasons that are irrelevant in tests, and also does not strip console annotations which are a distraction in test output.

Throws:

IOException

waitForCompletion

public <R extends hudson.model.Run<?,?>> R waitForCompletion(R r)
                                                      throws InterruptedException

Waits for a build to complete. Useful in conjunction with BuildWatcher.

Returns:

the same build, once done

Throws:

InterruptedException

Since:

1.607

waitForMessage

public <R extends hudson.model.Run<?,?>> R waitForMessage(String message,
                                                          R r)
                                                   throws IOException,
                                                          InterruptedException

Waits for a build log to contain a specified string. Useful in conjunction with BuildWatcher.

Returns:

the same build, once it does

Throws:

IOException

InterruptedException

Since:

1.607

assertXPath

public void assertXPath(com.gargoylesoftware.htmlunit.html.HtmlPage page,
                        String xpath)

Asserts that the XPath matches.

assertXPath

public void assertXPath(com.gargoylesoftware.htmlunit.html.DomNode page,
                        String xpath)

Asserts that the XPath matches the contents of a DomNode page. This variant of assertXPath(HtmlPage page, String xpath) allows us to examine XmlPages.

Parameters:

page -

xpath -

assertXPathValue

public void assertXPathValue(com.gargoylesoftware.htmlunit.html.DomNode page,
                             String xpath,
                             String expectedValue)

assertXPathValueContains

public void assertXPathValueContains(com.gargoylesoftware.htmlunit.html.DomNode page,
                                     String xpath,
                                     String needle)

assertXPathResultsContainText

public void assertXPathResultsContainText(com.gargoylesoftware.htmlunit.html.DomNode page,
                                          String xpath,
                                          String needle)

assertAllImageLoadSuccessfully

public void assertAllImageLoadSuccessfully(com.gargoylesoftware.htmlunit.html.HtmlPage p)

Makes sure that all the images in the page loads successfully. (By default, HtmlUnit doesn't load images.)

assertStringContains

public void assertStringContains(String message,
                                 String haystack,
                                 String needle)

assertStringContains

public void assertStringContains(String haystack,
                                 String needle)

assertHelpExists

public void assertHelpExists(Class<? extends hudson.model.Describable> type,
                             String properties)
                      throws Exception

Asserts that help files exist for the specified properties of the given instance.

Parameters:

type - The describable class type that should have the associated help files.

properties - ','-separated list of properties whose help files should exist.

Throws:

Exception

submit

public com.gargoylesoftware.htmlunit.html.HtmlPage submit(com.gargoylesoftware.htmlunit.html.HtmlForm form)
                                                   throws Exception

Submits the form. Plain HtmlForm.submit(com.gargoylesoftware.htmlunit.html.SubmittableElement) doesn't work correctly due to the use of YUI in Hudson.

Throws:

Exception

submit

public com.gargoylesoftware.htmlunit.html.HtmlPage submit(com.gargoylesoftware.htmlunit.html.HtmlForm form,
                                                          String name)
                                                   throws Exception

Submits the form by clicking the submit button of the given name.

Parameters:

name - This corresponds to the @name of <f:submit />

Throws:

Exception

findPreviousInputElement

public com.gargoylesoftware.htmlunit.html.HtmlInput findPreviousInputElement(com.gargoylesoftware.htmlunit.html.HtmlElement current,
                                                                             String name)

getButtonByCaption

public com.gargoylesoftware.htmlunit.html.HtmlButton getButtonByCaption(com.gargoylesoftware.htmlunit.html.HtmlForm f,
                                                                        String s)

createTaskListener

public hudson.model.TaskListener createTaskListener()

Creates a TaskListener connected to stdout.

assertEqualBeans

public void assertEqualBeans(Object lhs,
                             Object rhs,
                             String properties)
                      throws Exception

Asserts that two JavaBeans are equal as far as the given list of properties are concerned.

This method takes two objects that have properties (getXyz, isXyz, or just the public xyz field), and makes sure that the property values for each given property are equals (by using Assert.assertThat(Object, org.hamcrest.Matcher))

Property values can be null on both objects, and that is OK, but passing in a property that doesn't exist will fail an assertion.

This method is very convenient for comparing a large number of properties on two objects, for example to verify that the configuration is identical after a config screen roundtrip.

Parameters:

lhs - One of the two objects to be compared.

rhs - The other object to be compared

properties - ','-separated list of property names that are compared.

Throws:

Exception

Since:

1.297

setQuietPeriod

public void setQuietPeriod(int qp)

assertEqualDataBoundBeans

public void assertEqualDataBoundBeans(Object lhs,
                                      Object rhs)
                               throws Exception

Works like assertEqualBeans(Object, Object, String) but figure out the properties via DataBoundConstructor and DataBoundSetter

Throws:

Exception

assertEqualDataBoundBeans

public void assertEqualDataBoundBeans(List<?> lhs,
                                      List<?> rhs)
                               throws Exception

Makes sure that two collections are identical via assertEqualDataBoundBeans(Object, Object)

Throws:

Exception

findDataBoundConstructor

public Constructor<?> findDataBoundConstructor(Class<?> c)

get

public <T extends hudson.model.Descriptor<?>> T get(Class<T> d)

Gets the descriptor instance of the current Hudson by its type.

isSomethingHappening

public boolean isSomethingHappening()

Returns true if Hudson is building something or going to build something.

waitUntilNoActivity

public void waitUntilNoActivity()
                         throws Exception

Waits until Hudson finishes building everything, including those in the queue.

Throws:

Exception

waitUntilNoActivityUpTo

public void waitUntilNoActivityUpTo(int timeout)
                             throws Exception

Waits until Hudson finishes building everything, including those in the queue, or fail the test if the specified timeout milliseconds is

Throws:

Exception

recipe

public void recipe()
            throws Exception

Called during the before() to give a test case an opportunity to control the test environment in which Hudson is run.

One could override this method and call a series of withXXX methods, or you can use the annotations with Recipe meta-annotation.

Throws:

Exception

recipeLoadCurrentPlugin

public void recipeLoadCurrentPlugin()
                             throws Exception

If this test harness is launched for a Jenkins plugin, locate the target/test-classes/the.jpl and add a recipe to install that to the new Jenkins.

This file is created by maven-hpi-plugin at the testCompile phase when the current packaging is jpi.

Throws:

Exception

withNewHome

public JenkinsRule withNewHome()

withExistingHome

public JenkinsRule withExistingHome(File source)
                             throws Exception

Throws:

Exception

withPresetData

public JenkinsRule withPresetData(String name)

Declares that this test case expects to start with one of the preset data sets. See test/src/main/preset-data/ for available datasets and what they mean.

with

public JenkinsRule with(HudsonHomeLoader homeLoader)

executeOnServer

public <V> V executeOnServer(Callable<V> c)
                      throws Exception

Executes the given closure on the server, by the servlet request handling thread, in the context of an HTTP request.

In JenkinsRule, a thread that's executing the test code is different from the thread that carries out HTTP requests made through JenkinsRule.WebClient. But sometimes you want to make assertions and other calls with side-effect from within the request handling thread.

This method allows you to do just that. It is useful for testing some methods that require StaplerRequest and StaplerResponse, or getting the credential of the current user (via Jenkins.getAuthentication(), and so on.

Parameters:

c - The closure to be executed on the server.

Returns:

The return value from the closure.

Throws:

Exception - If a closure throws any exception, that exception will be carried forward.

createWebClient

public JenkinsRule.WebClient createWebClient()

This is to assist Groovy test clients who are incapable of instantiating the inner classes properly.

getTestDescription

public org.junit.runner.Description getTestDescription()