Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documented the RestartableJenkinsRule #7754

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+43 −1
Open

Documented the RestartableJenkinsRule #7754

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fd33fdb
documented the RestartableJenkinsRule
StefanSpieker Dec 15, 2024
0b98068
Apply suggestions from code review
StefanSpieker Dec 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 43 additions & 1 deletion content/doc/developer/testing/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -597,8 +597,50 @@ To use them in your plugin, please find documentation here:
* link:https://github.com/jenkins-infra/pipeline-library#runbenchmarks[Running benchmark through Jenkinsfile]

== Further Pipeline Testing

Sometimes you might need to test more sophisticated things, as restarting Jenkins and want to verify that the changes are still present.

=== Testing Durable Pipeline Steps
TODO: RestartableJenkinsRule.

If you want to ensure that your plugin behaves correctly after a restart, there are methods to help you.
`RestartableJenkinsRule` is part of the Jenkins testing framework and provides an easy way to simulate restarting Jenkins in your tests without actually having to restart the Jenkins instance.
You can use the `then()` method to run one Jenkins session and then shut down.
The following example shows how it can be used with a `FreeStyleJob` run which is verified after a Jenkins restart:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I lack fundamental skills in the use of RestartableJenkinsRule, so I'm not a great reviewer of this pull request. My apologies in advance for mistakes that I may make in the review process.

Since the example uses a FreeStyleProject, I think that the section heading should be changed from "Testing Durable Pipeline Steps" to "Testing Jenkins Restart". The example looks reasonable to me as a way to show that a FreeStyleProject build status persisted across a restart.

I think the job type used in the test should be referenced using the phrase "Freestyle job", the phrase "Freestyle project", or the Java class name "FreeStyleProject". The first two forms are used elsewhere in the www.jenkins.io documentation and the third is used in the example source code.

Suggested change
The following example shows how it can be used with a `FreeStyleJob` run which is verified after a Jenkins restart:
The following example shows how it can be used with a `FreeStyleProject` build which is verified after a Jenkins restart:


[source,java]
----
import hudson.model.FreeStyleProject;
import org.jvnet.hudson.test.RestartableJenkinsRule;
import org.junit.Rule;
import org.junit.Test;

public class MyPluginTest {

@Rule
public RestartableJenkinsRule rr = new RestartableJenkinsRule();

@Test
public void testPluginAfterRestart() {
rr.then(r -> {
// Set up the test environment
// e.g., create a job, configure your plugin, etc.
FreeStyleProject project = r.createFreeStyleProject("myJob");
// let's execute one build
project.scheduleBuild2(0).get();
});

// now we want to verify things after the restart
rr.then(r -> {
// get first project
FreeStyleProject p = (FreeStyleProject) r.getInstance().getAllItems().get(0);
// verify that it is still successfully
r.assertBuildStatusSuccess(p.getBuild("1"));
});
}
}
----

For more detailed information, you can take a look at the link:https://javadoc.jenkins.io/component/jenkins-test-harness/org/jvnet/hudson/test/RestartableJenkinsRule.html[`RestartableJenkinsRule` JavaDoc].

== Further Patterns
=== Custom builder
Expand Down
Loading