[JENKINS-26398] More flexible versions of createSlave

[jglick]

JENKINS-26398

Inspired by changes being made in jenkinsci/workflow-durable-task-step-plugin#180. Cleans up some tech debt from jenkinsci/pipeline-plugin#34 & jenkinsci/credentials-binding-plugin#3.

• Fixes createSlave overloads to use a more stable agent workdir compatible with JenkinsSessionRule.
• Introduces InboundAgentRule which is better suited to simulating agent disconnections.

[basil]

A common use case I have seen in plugins is the desire to create an agent with more than one executor for complex testing scenarios, for example in throttle-concurrent-builds. While I recognize that this is not a use case you are intending to address in this PR, I think it would be worth thinking about how to accommodate such a use case in a future change and designing the API to support (or at least not preclude) such a future use case.

[jglick]

Nothing precludes you from calling setNumExecutors on the return value.

[basil]

But if I recall correctly that might be too late, since we would have already launched the agent with the wrong number of executors, and setNumExecutors doesn't relaunch it. And it is awkward to launch with the wrong number and then relaunch with the correct number. So I think to accommodate such a future use case the API that launches the agent would need to support customizing the number of executors prior to launch. If the API you are proposing here can be extended to support that use case, great.

[jglick]

Since this requirement is pretty rare, and in fact there are only a handful of known use cases where specifically inbound agent is required (regular createSlave handles other cases), I am not inclined to complicate the API with an unused parameter. If and when somebody needs something like that, they could propose an API addition for it, or simply write their own agent launch code as was done previously.

[jglick]

Note: untested; I am not even exactly sure how you arrange for this property to be set in the Surefire JVM. Adapted from

jenkins-test-harness/src/main/java/org/jvnet/hudson/test/JenkinsRule.java

Line 1083 in 5ffb9b2

SLAVE_DEBUG_PORT>0 ? " -Xdebug -Xrunjdwp:transport=dt_socket,server=y,address="+(SLAVE_DEBUG_PORT+sz): "",

but compare

jenkins-test-harness/src/main/java/org/jvnet/hudson/test/RealJenkinsRule.java

Lines 466 to 468 in 5ffb9b2

	if (new DisableOnDebug(null).isDebugging()) {
	argv.add("-agentlib:jdwp=transport=dt_socket,server=y");
	}

which is fully automatic.

[basil]

Causes org.jenkinsci.plugins.workflow.steps.scm.SCMStepTest#checkoutsRestored to start failing with

java.lang.AssertionError: 

Expected: a string containing "Cloning the remote Git repository"
     but: was "Started by an SCM change
[Pipeline] Start of Pipeline
[Pipeline] node
Running on slave0 in /home/jenkins/workspace/Tools_bom_PR-1255/pct-work/workflow-scm-step/target/tmp/j h17894114103649561928/agent-work-dirs/slave0/workspace/p
[Pipeline] {
[Pipeline] ws
Running in /home/jenkins/workspace/Tools_bom_PR-1255/pct-work/workflow-scm-step/target/tmp/j h17894114103649561928/agent-work-dirs/slave0/workspace/p@2
[Pipeline] {
[Pipeline] git
The recommended git tool is: NONE
No credentials specified
Fetching changes from the remote Git repository
Checking out Revision 01ae2e7fa78cc0696363f238c012a7aff4240801 (refs/remotes/origin/master)
 > git rev-parse --resolve-git-dir /home/jenkins/workspace/Tools_bom_PR-1255/pct-work/workflow-scm-step/target/tmp/j h17894114103649561928/agent-work-dirs/slave0/workspace/p@2/.git # timeout=10
 > git config remote.origin.url /tmp/junit13354845484223236222/junit3675871739211897507 # timeout=10
Fetching upstream changes from /tmp/junit13354845484223236222/junit3675871739211897507
 > git --version # timeout=10
 > git --version # 'git version 2.34.1'
 > git fetch --tags --force --progress -- /tmp/junit13354845484223236222/junit3675871739211897507 +refs/heads/*:refs/remotes/origin/* # timeout=10
 > git rev-parse refs/remotes/origin/master^{commit} # timeout=10
 > git config core.sparsecheckout # timeout=10
 > git checkout -f 01ae2e7fa78cc0696363f238c012a7aff4240801 # timeout=10
 > git branch -a -v --no-abbrev # timeout=10
 > git branch -D master # timeout=10
 > git checkout -b master 01ae2e7fa78cc0696363f238c012a7aff4240801 # timeout=10
Commit message: "next"
 > git rev-list --no-walk c41f60902fcb334dd411f0032c66e949505c05dc # timeout=10
[Pipeline] }
[Pipeline] // ws
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
Finished: SUCCESS
"
	at org.hamcrest.MatcherAssert.assertThat(MatcherAssert.java:20)
	at org.hamcrest.MatcherAssert.assertThat(MatcherAssert.java:6)
	at org.jvnet.hudson.test.JenkinsRule.assertLogContains(JenkinsRule.java:1547)
	at org.jenkinsci.plugins.workflow.steps.scm.SCMStepTest.lambda$checkoutsRestored$2(SCMStepTest.java:125)
	at org.jvnet.hudson.test.RestartableJenkinsRule$3.evaluate(RestartableJenkinsRule.java:245)
	at org.jvnet.hudson.test.RestartableJenkinsRule$6.evaluate(RestartableJenkinsRule.java:293)
	at org.jvnet.hudson.test.JenkinsRule$1.evaluate(JenkinsRule.java:616)
	at org.junit.internal.runners.statements.FailOnTimeout$CallableStatement.call(FailOnTimeout.java:299)
	at org.junit.internal.runners.statements.FailOnTimeout$CallableStatement.call(FailOnTimeout.java:293)
	at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
	at java.base/java.lang.Thread.run(Thread.java:833)