Jenkins Pipeline Unit Testing: Mocking, Gotchas & Production Lessons

I still remember the Friday afternoon when a seemingly innocuous change to our deployment pipeline caused a 45-minute outage. The Jenkinsfile had a conditional that checked the branch name, but due to a typo in the regex, every branch triggered the production deployment. We had no tests for the pipeline logic. That incident sparked our journey into JenkinsPipelineUnit. We needed a way to test our Jenkinsfiles as rigorously as we test our application code. JenkinsPipelineUnit, combined with Spock, gave us that ability. Over the past two years, we've built a suite of over 200 pipeline tests covering everything from simple build steps to complex multi-branch deployment gates. In this article, I'll share the setup, patterns, and hard-won lessons from production.

1. Setting Up JenkinsPipelineUnit with Gradle

Getting started with JenkinsPipelineUnit requires adding the dependency to your build file. For Gradle, add to build.gradle:

testCompile group: 'com.lesfurets', name: 'jenkins-pipeline-unit', version: '1.0'

For Maven:

<dependency> <groupId>com.lesfurets</groupId> <artifactId>jenkins-pipeline-unit</artifactId> <version>1.0</version> <scope>test</scope> </dependency>

The framework provides a BasePipelineTest class that you extend. It sets up a mock Jenkins environment with helper methods for registering allowed methods. I recommend creating a base test class for your project that initializes common mocks. For example:

import com.lesfurets.jenkins.unit.BasePipelineTest

abstract class BasePipelineSpec extends BasePipelineTest { def setup() { super.setUp() helper.registerAllowedMethod('sh', [String]) { cmd -> println "Mocked sh: $cmd" return '' } helper.registerAllowedMethod('git', [String]) { url -> println "Mocked git: $url" } } }

This avoids repeating mocks in every test. The version 1.0+ is stable and widely used. Always use a specific version (like 1.0) rather than a range to avoid unexpected breaking changes.

2. Writing Your First Spock Test for a Scripted Pipeline

Let's write a test for a simple scripted Jenkinsfile that builds and tests. First, create a Jenkinsfile:

node { stage('Build') { sh 'make build' } stage('Test') { sh 'make test' } }

Now, create a Spock test:

class JenkinsfileTest extends BasePipelineSpec { def 'pipeline executes build and test stages'() { given: def script = loadPipelineScript('Jenkinsfile')

when: script.execute()

then: assert helper.callCount('sh') == 2 assert helper.callCount('stage') == 2 } }

The loadPipelineScript method loads the Jenkinsfile from the test resources. The execute() method runs the pipeline. We then assert that sh was called twice (once for build, once for test) and stage was called twice. This is a basic sanity check. In reality, you'll want to assert on the actual commands passed to sh. You can capture the arguments by storing them in a list:

def shCommands = [] helper.registerAllowedMethod('sh', [String]) { cmd -> shCommands << cmd; return '' }

Then assert: shCommands == ['make build', 'make test']

3. Testing Declarative Pipelines

Declarative pipelines require special handling because they are wrapped in a pipeline block. JenkinsPipelineUnit provides the pipelineModel() method to access the underlying model. For example, given a Jenkinsfile:

pipeline { agent any stages { stage('Build') { steps { sh 'make build' } } } }

Test it like this:

class DeclarativeTest extends BasePipelineSpec { def 'declarative pipeline runs build stage'() { given: def script = loadPipelineScript('Jenkinsfile') def pipeline = script.pipelineModel()

when: pipeline.execute()

then: assert helper.callCount('sh') == 1 } }

Note: The pipelineModel() method returns a PipelineModel object that has its own execute() method. If you call script.execute() directly on a declarative pipeline, it may not work. Also, you can access stages from the model:

pipeline.stages.each { stage -> println stage.name }

This is useful for asserting on the structure of your pipeline.

4. Mocking Steps: sh, git, withCredentials

Mocking is the heart of JenkinsPipelineUnit. You must register every step that your pipeline uses. Common steps include sh, git, withCredentials, checkout, etc. The registerAllowedMethod method takes the method name, a list of parameter types, and a closure. For example:

helper.registerAllowedMethod('sh', [String]) { cmd -> println "sh called with: $cmd" return '' }

For withCredentials, which takes a list of credentials and a closure:

helper.registerAllowedMethod('withCredentials', [List, Closure]) { creds, body -> body(creds) }

You can also mock methods that return values. For example, if you use readFile:

helper.registerAllowedMethod('readFile', [String]) { file -> return 'file content' }

It's important to match the exact parameter types. Use the same types as the actual Jenkins steps. When in doubt, check the JenkinsPipelineUnit source or use the debugger.

5. Testing Shared Library Methods

Shared libraries are a key part of Jenkins pipelines. To test them, you need to load the library and its methods. JenkinsPipelineUnit allows you to load shared library resources. Place your shared library code in src/ or vars/ directory in the test resources. For example, if you have a vars/deploy.groovy:

def call(String env) { sh "deploy $env" }

Test it like this:

class SharedLibraryTest extends BasePipelineSpec { def 'deploy method calls sh with correct argument'() { given: def script = loadScript('vars/deploy.groovy')

when: script.call('prod')

then: assert helper.callCount('sh') == 1 assert shCommands[0] == 'deploy prod' } }

You can also test methods that use pipeline steps by loading them in context of a pipeline script. For more complex scenarios, load the Jenkinsfile that uses the library and mock the library calls.

6. Testing Branch Logic in Multibranch Pipelines

Multibranch pipelines often have conditional logic based on the branch name. To test this, you need to set the BRANCH_NAME environment variable. For example:

node { if (env.BRANCH_NAME == 'main') { stage('Deploy') { sh 'deploy prod' } } else { stage('Test') { sh 'make test' } } }

Test it:

class BranchLogicTest extends BasePipelineSpec { def 'deploy stage runs on main branch'() { given: binding.setVariable('env', [BRANCH_NAME: 'main']) def script = loadPipelineScript('Jenkinsfile')

when: script.execute()

then: assert helper.callCount('stage') == 1 assert shCommands.contains('deploy prod') }

def 'test stage runs on feature branch'() { given: binding.setVariable('env', [BRANCH_NAME: 'feature/test']) def script = loadPipelineScript('Jenkinsfile')

when: script.execute()

then: assert helper.callCount('stage') == 1 assert shCommands.contains('make test') } }

You can also mock env directly via helper.registerAllowedMethod('env', []) { -> return binding.getVariable('env') }.

7. Mocking Credentials: usernamePassword and sshUserPrivateKey

Credentials are commonly used in pipelines. To mock withCredentials, you need to simulate the credential binding. For usernamePassword:

helper.registerAllowedMethod('withCredentials', [List, Closure]) { creds, body -> def credMap = [username: 'user', password: 'pass'] body(credMap) }

In the pipeline, you might use:

withCredentials([usernamePassword(credentialsId: 'mycreds', usernameVariable: 'USER', passwordVariable: 'PASS')]) { sh "echo $USER:$PASS" }

Your mock should pass a map that the pipeline expects. For sshUserPrivateKey:

helper.registerAllowedMethod('withCredentials', [List, Closure]) { creds, body -> def credMap = [keyFile: '/tmp/key', passphrase: ''] body(credMap) }

Alternatively, you can mock the individual credential variables by setting environment variables directly.

8. Testing Post Conditions and Error Handling

Jenkins pipelines have post sections that run based on build status. To test them, you need to simulate failures. For example:

node { stage('Build') { sh 'make build' } post { success { echo 'Build succeeded' } failure { echo 'Build failed' } } }

To test the failure post condition, make the sh step throw an exception:

helper.registerAllowedMethod('sh', [String]) { cmd -> throw new Exception('Build failed') }

Then assert:

when: script.execute()

then: thrown(Exception) assert helper.callCount('echo') == 1 // Or assert on build result via pipeline.getBuildResult() == 'FAILURE'

If you use declarative pipeline, you can access the build result from the pipeline model:

pipeline.getBuildResult() // returns 'SUCCESS' or 'FAILURE'

Also test that the success post condition runs when no exception is thrown.

9. Writing Assertion Tests for Build Status

Asserting on build status is crucial. JenkinsPipelineUnit provides a method getBuildResult() on the pipeline model for declarative pipelines. For scripted pipelines, you can check the result via the internal state. A common pattern:

when: def result = script.execute()

then: assert result == 'SUCCESS' // or 'FAILURE'

But note: for scripted pipelines, execute() returns the result string. For declarative, you need to call pipelineModel().execute() and then pipelineModel().getBuildResult().

You can also assert on the number of times a stage was executed:

assert helper.callCount('stage') == 2

And on specific steps:

assert helper.callCount('sh') == 1

For more granularity, capture the arguments as shown earlier.

10. Test Coverage for Pipeline Code

Code coverage for pipeline scripts is important but tricky. JenkinsPipelineUnit does not generate coverage reports directly. However, you can use JaCoCo with Groovy. Add the JaCoCo plugin to your build and configure it to include the pipeline scripts. For Gradle:

apply plugin: 'jacoco' jacocoTestReport { executionData test sourceSets sourceSets.main // Include pipeline scripts directory additionalSourceDirs files('src/main/groovy') sourceDirectories files('src/main/groovy') classDirectories files('build/classes/groovy/main') }

Place your Jenkinsfile in src/main/groovy (or as a resource) and it will be instrumented. Ensure your test loads the script from the classpath. You can also use the Cobertura plugin. The goal is to measure which lines of the Jenkinsfile are executed by your tests. Aim for at least 80% coverage on critical paths like deployment gates.

11. CI Integration: Running Pipeline Tests on Every PR

To get the full benefit, run your pipeline tests in CI whenever the Jenkinsfile or shared library changes. For example, in your GitHub Actions workflow:

name: Pipeline Tests on: pull_request: paths: - 'Jenkinsfile' - 'vars/' - 'src/'

jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up JDK 11 uses: actions/setup-java@v1 with: java-version: 11 - name: Run tests run: ./gradlew test - name: Generate coverage report run: ./gradlew jacocoTestReport - name: Upload coverage uses: actions/upload-artifact@v2 with: name: coverage path: build/reports/jacoco/test/html

This ensures that every PR to the pipeline code is validated. You can also add a status check that requires the tests to pass before merging.

12. Common Mocking Pitfalls and How to Avoid Them

Pitfall 1: Non-serializable errors. JenkinsPipelineUnit sometimes throws NotSerializableException when closures capture non-serializable objects. Solution: avoid capturing external objects in closures; use simple closures that only reference primitives or strings.

Pitfall 2: Missing method registration. The most common error is MissingMethodException. Solution: always register all methods your pipeline uses. Use a setup method in your base test class that mocks all common steps.

Pitfall 3: Incorrect parameter types. registerAllowedMethod requires exact parameter types. For example, sh can be called with a String or a Map. Register both:

helper.registerAllowedMethod('sh', [String]) { ... } helper.registerAllowedMethod('sh', [Map]) { ... }

Pitfall 4: Forgetting to mock methods in shared libraries. Solution: when loading a shared library script, ensure you mock the steps it uses as well.

Pitfall 5: Mocking too much. Over-mocking can hide real issues. Only mock external steps; keep your pipeline logic as real as possible.