• Stars
    star
    1,426
  • Rank 31,429 (Top 0.7 %)
  • Language
    Groovy
  • License
    MIT License
  • Created about 7 years ago
  • Updated 12 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Framework for unit testing Jenkins pipelines

JenkinsPipelineUnit Testing Framework

Jenkins Pipeline Unit is a testing framework for unit testing Jenkins pipelines, written in Groovy Pipeline DSL.

Linux/Windows Build status Mac Build status GitHub release (latest SemVer) Gitter chat

If you use Jenkins as your CI workhorse (like us @ lesfurets.com) and you enjoy writing pipeline-as-code, you already know that pipeline code is very powerful but can get pretty complex.

This testing framework lets you write unit tests on the configuration and conditional logic of the pipeline code, by providing a mock execution of the pipeline. You can mock built-in Jenkins commands, job configurations, see the stacktrace of the whole execution and even track regressions.

Table of Contents

  1. Usage
  2. Configuration
  3. Declarative Pipeline
  4. Testing Shared Libraries
  5. Writing Testable Libraries
  6. Note On CPS
  7. Contributing
  8. Demos and Examples

Usage

Add to Your Project as Test Dependency

JenkinsPipelineUnit requires Java 11, since this is also the minimum version required by Jenkins. Also note that JenkinsPipelineUnit is not currently compatible with Groovy 4, please see this issue for more details.

Note: Starting from version 1.2, artifacts are published to https://repo.jenkins-ci.org/releases.

Maven

<repositories>
    <repository>
    <id>jenkins-ci-releases</id>
    <url>https://repo.jenkins-ci.org/releases/</url>
    </repository>
    ...
</repositories>

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

Gradle

repositories {
    maven { url 'https://repo.jenkins-ci.org/releases/' }
    ...
}

dependencies {
    testImplementation "com.lesfurets:jenkins-pipeline-unit:1.9"
    ...
}

Start Writing Tests

You can write your tests in Groovy or Java, using the test framework you prefer. The easiest entry point is extending the abstract class BasePipelineTest, which initializes the framework with JUnit.

Let's say you wrote this awesome pipeline script, which builds and tests your project:

def execute() {
    node() {
        String utils = load 'src/test/jenkins/lib/utils.jenkins'
        String revision = stage('Checkout') {
            checkout scm
            return utils.currentRevision()
        }
        gitlabBuilds(builds: ['build', 'test']) {
            stage('build') {
                gitlabCommitStatus('build') {
                    sh "mvn clean package -DskipTests -DgitRevision=$revision"
                }
            }

            stage('test') {
                gitlabCommitStatus('test') {
                    sh "mvn verify -DgitRevision=$revision"
                }
            }
        }
    }
}

return this

Now using the Jenkins Pipeline Unit you can write a unit test to see if it does the job:

import com.lesfurets.jenkins.unit.BasePipelineTest

class TestExampleJob extends BasePipelineTest {
    @Test
    void shouldExecuteWithoutErrors() {
        loadScript('job/exampleJob.jenkins').execute()
        printCallStack()
    }
}

This test will print the call stack of the execution, which should look like so:

   exampleJob.run()
   exampleJob.execute()
      exampleJob.node(groovy.lang.Closure)
         exampleJob.load(src/test/jenkins/lib/utils.jenkins)
            utils.run()
         exampleJob.stage(Checkout, groovy.lang.Closure)
            exampleJob.checkout({$class=GitSCM, branches=[{name=feature_test}], extensions=[], userRemoteConfigs=[{credentialsId=gitlab_git_ssh, url=github.com/lesfurets/JenkinsPipelineUnit.git}]})
            utils.currentRevision()
               utils.sh({returnStdout=true, script=git rev-parse HEAD})
         exampleJob.gitlabBuilds({builds=[build, test]}, groovy.lang.Closure)
            exampleJob.stage(build, groovy.lang.Closure)
               exampleJob.gitlabCommitStatus(build, groovy.lang.Closure)
                  exampleJob.sh(mvn clean package -DskipTests -DgitRevision=bcc19744)
            exampleJob.stage(test, groovy.lang.Closure)
               exampleJob.gitlabCommitStatus(test, groovy.lang.Closure)
                  exampleJob.sh(mvn verify -DgitRevision=bcc19744)

Mocking Jenkins Variables

You can define both environment variables and job execution parameters.

import com.lesfurets.jenkins.unit.BasePipelineTest

class TestExampleJob extends BasePipelineTest {
    @Override
    @BeforeEach
    void setUp() {
        super.setUp()
        // Assigns false to a job parameter ENABLE_TEST_STAGE
        addParam('ENABLE_TEST_STAGE', 'false')
        // Defines the previous execution status
        binding.getVariable('currentBuild').previousBuild = [result: 'UNSTABLE']
    }

    @Test
    void verifyParam() {
        assertEquals('false', binding.getVariable('params')['ENABLE_TEST_STAGE'])
    }
}

After calling super.setUp(), the test helper instance is available, as well as many helper methods. The test helper already provides basic variables such as a very simple currentBuild definition. You can redefine them as you wish.

Note that super.setUp() must be called prior to using most features. This is commonly done using your own setUp method, decorated with @Override and @BeforeEach.

Parameters added via addParam are immutable, which reflects the same behavior in Jenkins. Attempting to modify the params map in the binding will result in an error.

Mocking Jenkins Commands

You can register interceptors to mock pipeline methods, including Jenkins commands, which may or may not return a result.

import com.lesfurets.jenkins.unit.BasePipelineTest

class TestExampleJob extends BasePipelineTest {
    @Override
    @BeforeEach
    void setUp() {
        super.setUp()
        helper.registerAllowedMethod('sh', [Map]) { args -> return 'bcc19744' }
        helper.registerAllowedMethod('timeout', [Map, Closure], null)
        helper.registerAllowedMethod('timestamps', []) { println 'Printing timestamp' }
        helper.registerAllowedMethod('myMethod', [String, int]) { String s, int i ->
            println "Executing myMethod mock with args: '${s}', '${i}'"
        }
    }
}

The test helper already includes mocks for all base pipeline steps as well as a steps from a few widely-used plugins. You need to register allowed methods if you want to override these mocks and add others. Note that you need to provide a method signature and a callback (closure or lambda) in order to allow a method. Any method call which is not recognized will throw an exception.

Please refer to the BasePipelineTest class for the list of currently supported mocks.

Some tricky methods such as load and parallel are implemented directly in the helper. If you want to override those, make sure that you extend the PipelineTestHelper class.

Mocking readFile and fileExists

The readFile and fileExists steps can be mocked to return a specific result for a given file name. This can be useful for testing pipelines for which file operations can influence subsequent steps. An example of such a testing scenario follows:

// Jenkinsfile
node {
    stage('Process output') {
        if (fileExists('output') && readFile('output') == 'FAILED!!!') {
            currentBuild.result = 'FAILURE'
            error 'Build failed'
        }
    }
}
@Test
void exampleReadFileTest() {
    helper.addFileExistsMock('output', true)
    helper.addReadFileMock('output', 'FAILED!!!')

    runScript('Jenkinsfile')

    assertJobStatusFailure()
}

Mocking Shell Steps

The shell steps (sh, bat, etc) are used by many pipelines for a variety of tasks. They can be mocked to either (a) statically return:

  • A string for standard output
  • A return code

Or (b), to execute a closure that returns a Map (with stdout and exitValue entries). The closure will be executed when the shell is called, allowing for dynamic behavior.

Here is a sample pipeline and corresponding unit tests for each of these variants.

// Jenkinsfile
node {
    stage('Mock build') {
        String systemType = sh(returnStdout: true, script: 'uname')
        if (systemType == 'Debian') {
            sh './build.sh --release'
            int status = sh(returnStatus: true, script: './test.sh')
            if (status > 0) {
                currentBuild.result = 'UNSTABLE'
            } else {
                def result = sh(
                    returnStdout: true,
                    script: './processTestResults.sh --platform debian',
                )
                if (!result.endsWith('SUCCESS')) {
                    currentBuild.result = 'FAILURE'
                    error 'Build failed!'
                }
            }
        }
    }
}
@Test
void debianBuildSuccess() {
    helper.addShMock('uname', 'Debian', 0)
    helper.addShMock('./build.sh --release', '', 0)
    helper.addShMock('./test.sh', '', 0)
    // Have the sh mock execute the closure when the corresponding script is run:
    helper.addShMock('./processTestResults.sh --platform debian') { script ->
        // Do something "dynamically" first...
        return [stdout: "Executing ${script}: SUCCESS", exitValue: 0]
    }

    runScript("Jenkinsfile")

    assertJobStatusSuccess()
}

@Test
void debianBuildUnstable() {
    helper.addShMock('uname', 'Debian', 0)
    helper.addShMock('./build.sh --release', '', 0)
    helper.addShMock('./test.sh', '', 1)

    runScript('Jenkinsfile')

    assertJobStatusUnstable()
}

Note that in all cases, the script executed by sh must exactly match the string passed to helper.addShMock, including the script arguments, whitespace, etc. For more flexible matching, you can use a pattern (regular expression) and even capture groups:

helper.addShMock(~/.\/build.sh\s--(.*)/) { String script, String arg ->
    assert (arg == 'debug') || (arg == 'release')
    return [stdout: '', exitValue: 2]
}

Also, mocks are stacked, so if two mocks match a call, the last one wins. Combined with a match-everything mock, you can tighten your tests a bit:

@BeforeEach
void setUp() {
    super.setUp()
    helper = new PipelineTestHelper()
    // Basic `sh` mock setup:
    // - generate an error on unexpected calls
    // - ignore any echo (debug) outputs, they are not relevant
    // - all further shell mocks are configured in the test
    helper.addShMock(null) { throw new Exception('Unexpected sh call') }
    helper.addShMock(~/echo\s.*/, '', 0)
}

Analyzing the Mock Execution

The helper registers every method call to provide a stacktrace of the mock execution.

@Test
void shouldExecuteWithoutErrors() {
    runScript('Jenkinsfile')

    assertJobStatusSuccess()
    assertThat(helper.callStack.findAll { call ->
        call.methodName == 'sh'
    }.any { call ->
        callArgsToString(call).contains('mvn verify')
    }).isTrue()
}

This will also check that mvn verify was called during the job execution.

Checking Pipeline Status

Let's say you have a simple script, and you'd like to check its behavior if a step fails.

// Jenkinsfile
node() {
    git 'some_repo_url'
    sh 'make'
}

You can mock the sh step to just update the pipeline status to FAILURE. To verify that your pipeline is failing, you need to check the status with BasePipelineTest.assertJobStatusFailure().

@Test
void checkBuildStatus() {
    helper.registerAllowedMethod('sh', [String]) { cmd ->
        if (cmd == 'make') {
            binding.getVariable('currentBuild').result = 'FAILURE'
        }
    }

    runScript('Jenkinsfile')

    assertJobStatusFailure()
}

Checking Pipeline Exceptions

Sometimes it is useful to verify that a specific exception was thrown during the pipeline run. JUnit 4 and 5 have slightly different mechanisms for doing this.

For both examples below, assume that the following pipeline is being tested:

To do so you can use org.junit.rules.ExpectedException

// Jenkinsfile
node {
    throw new IllegalArgumentException('oh no!')
}

JUnit 4

class TestCase extends BasePipelineTest {
    @Test(expected = IllegalArgumentException)
    void verifyException() {
        runScript('Jenkinsfile')
    }
}

JUnit 5

import static org.junit.jupiter.api.Assertions.assertThrows

class TestCase extends BasePipelineTest {
    @Test
    void verifyException() {
        assertThrows(IllegalArgumentException) { runScript('Jenkinsfile') }
    }
}

Compare the Callstack with a Previous Implementation

One other use of the callstacks is to check your pipeline executions for possible regressions. You have a dedicated method you can call if you extend BaseRegressionTest:

@Test
void testPipelineNonRegression() {
    loadScript('job/exampleJob.jenkins').execute()
    super.testNonRegression('example')
}

This will compare the current callstack of the job to the one you have in a text callstack reference file. To update this file with new callstack, just set this JVM argument when running your tests: -Dpipeline.stack.write=true. You then can go ahead and commit this change in your SCM to check in the change.

Preserve Original Callstack Argument References

The default behavior of the callstack capture is to clone each call's arguments to preserve their values at time of the call should those arguments mutate downstream. That is a good guard when your scripts are passing ordinary mutable variables as arguments.

However, argument types that are not Cloneable are captured as String values. Most of the time this is a perfect fallback. But for some complex types, or for types that don't implement toString(), it can be tricky or impossible to validate the call values in a test.

Take the following simple example:

Map pretendArgsFromFarUpstream = [
    foo: 'bar',
    foo2: 'more bar please',
    aNestedMap: [aa: 1, bb: 2],
    plusAList: [1, 2, 3, 4],
].asImmutable()

node() {
    doSomethingWithThis(pretendArgsFromFarUpstream)
}

pretendArgsFromFarUpstream is an immutable map and will be recorded as a String in the callstack. Your test may want to perform fine-grained validations via map key referencing instead of pattern matching or similar parsing. For example:

assertEquals(2, arg.aNestedMap.bb)

You may want to perform this kind of validation, particularly if your pipelines pass final and/or immutable variables as arguments. You can retain the direct reference to the variable in the callstack by setting this switch in your test setup:

helper.cloneArgsOnMethodCallRegistration = false

Running Inline Scripts

In case you want to have some script executed directly within a test case rather than creating a resource file for it, loadInlineScript and runInlineScript can be used.

@Test
void testSomeScript() {
    Object script = loadInlineScript('''
        node {
            stage('Build') {
                sh 'make'
            }
        }
    ''')

    script.execute()

    printCallStack()
    assertJobStatusSuccess()
}

Note that inline scripts cannot be debugged via breakpoints as there is no file to attach to!

Configuration

The abstract class BasePipelineTest configures the helper with useful conventions:

  • It looks for pipeline scripts in your project in root (./.) and src/main/jenkins paths.
  • Jenkins pipelines let you load other scripts from a parent script with load command. However load takes the full path relative to the project root. The test helper mock successfully the load command to load the scripts. To make relative paths work, you need to configure the path of the project where your pipeline scripts are, which defaults to ..
  • Pipeline script extension, which defaults to jenkins (matches any *.jenkins file)

Overriding these default values is easy:

class TestExampleJob extends BasePipelineTest {
    @Override
    @BeforeEach
    void setUp() {
        baseScriptRoot = 'jenkinsJobs'
        scriptRoots += 'src/main/groovy'
        scriptExtension = 'pipeline'
        super.setUp()
    }
}

This will work fine for such a project structure:

 jenkinsJobs
 └── src
     ├── main
     │   └── groovy
     │       └── ExampleJob.pipeline
     └── test
         └── groovy
             └── TestExampleJob.groovy

Declarative Pipelines

To test a declarative pipeline, you'll need to subclass the DeclarativePipelineTest class instead of BasePipelineTest

// Jenkinsfile
pipeline {
    agent none
    stages {
        stage('Example Build') {
            agent { docker 'maven:3-alpine' }
            steps {
                echo 'Hello, Maven'
                sh 'mvn --version'
            }
        }
        stage('Example Test') {
            agent { docker 'openjdk:8-jre' }
            steps {
                echo 'Hello, JDK'
                sh 'java -version'
            }
        }
    }
}
import com.lesfurets.jenkins.unit.declarative.*

class TestExampleDeclarativeJob extends DeclarativePipelineTest {
    @Test
    void shouldExecuteWithoutErrors() {
        runScript("Jenkinsfile")

        assertJobStatusSuccess()
        printCallStack()
    }
}

DeclarativePipelineTest

The DeclarativePipelineTest class extends BasePipelineTest, so you can verify your declarative job the same way as scripted pipelines.

Testing Pipelines That Use Shared Libraries

With Shared Libraries, Jenkins lets you share common code from pipelines across different repositories. Shared libraries are configured in the Jenkins settings and imported with @Library annotation or the library step.

Testing pipeline scripts using external libraries is not trivial because the shared library code is another repository. JenkinsPipelineUnit lets you test shared libraries and pipelines that depend on these libraries.

Here is an example pipeline using a shared library:

@Library('commons')

import net.courtanet.jenkins.Utils

sayHello 'World'

node() {
    stage ('Checkout') {
        def utils = new Utils()
        checkout "${utils.gitTools()}"
    }
    stage ('Build') {
        sh './gradlew build'
    }
    stage ('Post Build') {
        String json = libraryResource 'net/courtanet/jenkins/request.json'
        sh "curl -H 'Content-Type: application/json' -X POST -d '$json' ${acme.url}"
    }
}

This pipeline is using a shared library called commons. Now let's test it:

// You need to import the class first
import static com.lesfurets.jenkins.unit.global.lib.LibraryConfiguration.library

class TestCase extends BasePipelineTest {
    @Test
    void testLibrary() {
        Object library = library()
            .name('commons')
            .retriever(gitSource('[email protected]:libs/commons.git'))
            .targetPath('path/to/clone')
            .defaultVersion("master")
            .allowOverride(true)
            .implicit(false)
            .build()
        helper.registerSharedLibrary(library)

        runScript('job/library/exampleJob.jenkins')

        printCallStack()
    }
}

Notice how the shared library is defined and registered to the helper. The library definition is done via a fluent API which lets you set the same configurations as in Jenkins Global Pipeline Libraries.

The retriever and targetPath fields tell the framework how to fetch the sources of the library, and to which local path. The framework comes with two naive but useful retrievers, gitSource and localSource. You can write your own retriever by implementing the SourceRetriever interface.

Note that properties defaultVersion, allowOverride and implicit are optional with default values master, true and false.

Now if we execute this test, the framework will fetch the sources from the Git repository and load classes, scripts, global variables and resources found in the library. The callstack of this execution will look like the following:

Loading shared library commons with version master
libraryJob.run()
  libraryJob.sayHello(World)
  sayHello.echo(Hello, World.)
  libraryJob.node(groovy.lang.Closure)
     libraryJob.stage(Checkout, groovy.lang.Closure)
        Utils.gitTools()
        libraryJob.checkout({branch=master})
     libraryJob.stage(Build, groovy.lang.Closure)
        libraryJob.sh(./gradlew build)
     libraryJob.stage(Post Build, groovy.lang.Closure)
        libraryJob.libraryResource(net/courtanet/jenkins/request.json)
        libraryJob.sh(curl -H 'Content-Type: application/json' -X POST -d '{"name" : "Ben"}' http://acme.com)

Library Source Retrievers

There are a few types of SourceRetriever implementations in addition to the previously described GitSource one.

ProjectSource Retriever

The ProjectSource retriever is useful if you write tests for the library itself. So it lets you load the library files directly from the project root folder (where the src and vars folders are located).

Then you can use projectSource to point to the location of the library files. Calling projectSource() with no arguments will look for files in the project root. With .defaultVersion('<notNeeded>'), you can load it in pipelines using commons@master or commons@features which would use the same repository.

import static com.lesfurets.jenkins.unit.global.lib.ProjectSource.projectSource

class TestCase extends BasePipelineTest {
    @Override
    @BeforeEach
    void setUp() {
        super.setUp()
        Object library = library()
            .name('commons')
            .defaultVersion('<notNeeded>')
            .allowOverride(true)
            .implicit(true)
            .targetPath('<notNeeded>')
            .retriever(projectSource())
            .build()
        helper.registerSharedLibrary(library)
    }
}

LocalSource Retriever

The LocalSource retriever is useful if you want to verify how well your library integrates with the pipelines. For example you may use pre-copied library files with different versions.

import static com.lesfurets.jenkins.unit.global.lib.LocalSource.localSource

class TestCase extends BasePipelineTest {
    @Override
    @BeforeEach
    void setUp() {
        super.setUp()
        Object library = library()
            .name('commons')
            .defaultVersion('master')
            .allowOverride(true)
            .implicit(false)
            .targetPath('<notNeeded>')
            .retriever(localSource('/var/tmp/'))
            .build()
        helper.registerSharedLibrary(library)
    }
}

In the above example, the retriever would assume that the library files are located at /var/tmp/commons@master.

Loading Libraries Dynamically

There is partial support for loading dynamic libraries. It doesn't implement all the features, but it could be useful sometimes.

Pipeline example:

Object commonsLib = library 'commons'

// Assume that `sayHello` is a singleton in the `commons` library
sayHello 'World'

// Create an instance of a class in the `commons` library
Object utils = net.courtanet.jenkins.Utils.new()

Test class example:

@Test
void testDynamicLibrary() {
    Object library = library()
        .name('commons')
        .retriever(gitSource('[email protected]:libs/commons.git'))
        .targetPath('path/to/clone')
        .defaultVersion('master')
        .allowOverride(true)
        .implicit(false)
        .build()
    helper.registerSharedLibrary(library)
    // Registration for pipeline method 'library' must be made after registering the
    // shared library. Unfortunately, this cannot be moved to the super class.
    helper.registerAllowedMethod('library', [String], { String name ->
        helper.getLibLoader().loadLibrary(name)
        println helper.getLibLoader().libRecords
        return new LibClassLoader(helper, null)
    })

    loadScript('job/library/exampleJob.jenkins')

    printCallStack()
}

Library Global Variables with Library Object Arguments

You might have a library that defines global variables with library class instances as arguments. For example, consider the following library class and global variable:

// src/com/example/Monster.groovy
package com.example

class Monster {
    String moniker

    Monster(String moniker) {
      this.moniker = moniker
    }
}
// vars/monster.groovy
import com.example.Monster

void call(Monster monster) {
    println "${monster.moniker} is always very scary"
}

Your pipeline uses both as follows:

Monster vampire = new Monster('Dracula')
monster(vampire)
// Should print "Dracula is always very scary"

If this does not yield the expected output but instead throws a MissingMethodException with the cause No signature of method: Jenkinsfile.monster() is applicable for argument types: (org.test.Monster) values: [com.example.Monster1@d34db33f] you may need to disable library class preloading in your test setup, which you do with the following switch.

helper.libLoader.preloadLibraryClasses = false

You may need to do this on a test-by-test basis, as disabling class preloading can cause problems in other cases. For example, when you have library classes that require access to the env global.

Writing Testable Libraries

We recommend the following best-practices for organizing pipeline code:

  • Keep complex logic in the Jenkinsfile to a minimum
    • When possible, move complexity to external scripts that the Jenkinsfile executes
    • Move shared functionality to pipeline libraries
    • Likewise, any tricky Groovy logic that can't be easily moved to external scripts should also be placed in pipeline libraries
  • In pipeline libraries, organize logic in classes under src
    • Ideally, JenkinsPipelineUnit is used to test only these classes
  • Use the vars singletons to instantiate classes from src

On External Scripts

In general, it's better to avoid having complex build logic inside of build pipelines. Although tools like JenkinsPipelineUnit are useful in testing pipelines, it's much easier to run build scripts locally (meaning, outside of a Jenkins environment). Languages like Python have much more sophisticated linting and testing tools than Groovy does.

That said, CodeNarc can be used to lint Groovy code, including Jenkinsfile files.

On Pipeline Library Organization

We recommend organizing pipeline libraries such that the bulk of the logic is organized into classes, and the singletons being thin wrappers around these classes. This approach has several advantages:

  • It makes it easier to use OOP practices to organize the code
  • It solves the problem of having to mock singletons inside of other singletons for tests
  • It forces the script context to be injected into the class, which means less mocking of @Library calls and such

Example Pipeline Library Organization

Let's say we have a library responsible for a very complex operation, in this case, adding two numbers together. 😄 Here's what that library (let's call it HardMath) might look like:

// src/com/example/HardMath.groovy
package com.example

class HardMath implements Serializable {
  // Jenkinsfile script context, note that all pipeline steps must use this context
  Object script = null

  int complexOperation(int a, int b) {
    // Note the script context is required for `echo`, as it is a pipeline step
    script.echo "Adding ${a} to ${b}"
    return a + b
  }
}
// vars/hardmath.groovy
import com.example.HardMath

int complexOperation(int a, int b) {
  return new HardMath(script: this).complexOperation(a, b)
}
// test/com/example/HardMathTest.groovy
package com.example

import static org.junit.jupiter.api.Assertions.assertEquals

import com.lesfurets.jenkins.unit.BasePipelineTest
import org.junit.jupiter.api.BeforeEach
import org.junit.jupiter.api.Test


class HardMathTest extends BasePipelineTest {
  Object script = null

  @Override
  @BeforeEach
  void setUp() {
    super.setUp()
    this.script = loadScript('test/resources/EmptyPipeline.groovy')
  }

  @Test
  void testComplexOperation() {
    int result = new HardMath(script: script).complexOperation(1, 3)
    assertEquals(4, result)
  }
}
// test/resources/EmptyPipeline.groovy
return this

And finally, in some other project's Jenkinsfile:

// Jenkinsfile
@Library('hardmath')

node {
  stage('Hard Math') {
    int result = hardmath.complexOperation(5, 6)
    echo "The result is ${result}"
  }
}

For a larger real-world example of a pipeline library organized like the above and tested with JenkinsPipelineUnit, have a look at python-pipeline-utils.

Note on CPS

If you already fiddled with Jenkins pipeline DSL, you may have experienced strange errors during execution on Jenkins. This is because Jenkins does not directly execute your pipeline in Groovy, but transforms the pipeline code into an intermediate format in order to run Groovy code in Continuation Passing Style (CPS).

The usual errors are partly due to the the sandboxing Jenkins applies for security reasons, and partly due to the serializability Jenkins imposes.

Jenkins requires that at each execution step, the whole script context is serializable, in order to stop and resume the job execution. To simulate this aspect, CPS versions of the helpers transform your scripts into the CPS format and check if at each step your script context is serializable.

To use this experimental feature, you can use the abstract class BasePipelineTestCPS instead of BasePipelineTest. You may see some changes in the callstacks that the helper registers. Note also that the serialization used to test is not the same as what Jenkins uses. You may find some incoherence in that respect.

Contributing

JenkinsPipelineUnit aims to help developers code and test Jenkins pipelines with a shorter development cycle. It addresses some of the requirements traced in JENKINS-33925. If you are willing to contribute please don't hesitate to discuss in issues and open a pull-request.

Demos and Examples

URL Frameworks and Tools Test Subject Test Layers
https://github.com/macg33zr/pipelineUnit Spock, Gradle(Groovy) Jenkinsfile, scripted pipeline, SharedLibrary UnitTest
https://github.com/mkobit/jenkins-pipeline-shared-library-example Spock, Gradle (Kotlin), Junit SharedLibrary Integration, Unit
https://github.com/stchar/pipeline-sharedlib-testharness Junit, Gradle(Groovy) SharedLibrary Integration, Unit
https://github.com/stchar/pipeline-dsl-seed Junit, Spock, Gradle(Groovy) scripted pipeline Integration(jobdsl), Unit
https://github.com/SpencerMalone/JenkinsPipelineIntegration Spock, Gradle(Groovy) SharedLibrary Integration
https://github.com/venosov/jenkins-pipeline-shared-library-example-victor Junit, Gradle(Kotlin) SharedLibrary Unit

More Repositories

1

jenkins

Jenkins automation server
Java
21,381
star
2

docker

Docker official jenkins repo
Dockerfile
6,144
star
3

pipeline-examples

A collection of examples, tips and tricks and snippets of scripting for the Jenkins Pipeline plugin
Groovy
4,117
star
4

blueocean-plugin

Blue Ocean is a reboot of the Jenkins CI/CD User Experience
Java
2,874
star
5

configuration-as-code-plugin

Jenkins Configuration as Code Plugin
Java
2,521
star
6

kubernetes-plugin

Jenkins plugin to run dynamic agents in a Kubernetes/Docker environment
Java
2,206
star
7

job-dsl-plugin

A Groovy DSL for Jenkins Jobs - Sweeeeet!
Groovy
1,851
star
8

pipeline-plugin

Obsolete home for Pipeline plugins
1,711
star
9

gitlab-plugin

A Jenkins plugin for interfacing with GitLab
Java
1,418
star
10

jenkinsfile-runner

A command line tool to run Jenkinsfile as a function
Java
1,096
star
11

java-client-api

A Jenkins API client for Java
Java
888
star
12

jenkins-scripts

Scripts in Groovy, shell, Ruby, Python, whatever for managing/interacting with Jenkins
Groovy
880
star
13

build-monitor-plugin

Jenkins Build Monitor Plugin
Java
722
star
14

slack-plugin

A Jenkins plugin for posting notifications to a Slack channel
Java
664
star
15

git-plugin

Git repository access for Jenkins jobs
Java
660
star
16

pipeline-model-definition-plugin

Groovy
557
star
17

ghprb-plugin

github pull requests builder plugin for Jenkins
Java
495
star
18

docker-workflow-plugin

Jenkins plugin which allows building, testing, and using Docker images from Jenkins Pipeline projects.
Java
492
star
19

docker-plugin

Jenkins Cloud Plugin that uses Docker
Java
482
star
20

docker-inbound-agent

Docker image for a Jenkins agent which can connect to Jenkins using TCP or Websocket protocols
PowerShell
466
star
21

helm-charts

Jenkins helm charts
Mustache
448
star
22

pipeline-aws-plugin

Jenkins Pipeline Step Plugin for AWS
Java
423
star
23

jenkins.rb

Deprecated, see https://www.jenkins.io/jep/7
Ruby
394
star
24

generic-webhook-trigger-plugin

Can receive any HTTP request, extract any values from JSON or XML and trigger a job with those values available as variables. Works with GitHub, GitLab, Bitbucket, Jira and many more.
Java
377
star
25

email-ext-plugin

Jenkins Email Extension Plugin
Java
338
star
26

dingtalk-plugin

Dingtalk for jenkins
Java
336
star
27

warnings-ng-plugin

Jenkins Warnings Plugin - Next Generation
Java
323
star
28

plugin-installation-manager-tool

Plugin Manager CLI tool for Jenkins
Java
301
star
29

mesos-plugin

Mesos Cloud Jenkins Plugin
Java
291
star
30

github-plugin

Jenkins GitHub plugin
Java
286
star
31

ec2-plugin

Jenkins ec2 plugin
Java
282
star
32

ssh-steps-plugin

Jenkins pipeline steps which provides SSH facilities such as command execution or file transfer for continuous delivery.
Java
273
star
33

ansicolor-plugin

Jenkins ANSI Color Plugin
Java
253
star
34

pipeline-utility-steps-plugin

Small, miscellaneous, cross platform utility steps for Jenkins Pipeline jobs.
Java
237
star
35

docker-agent

Base Docker image for Jenkins Agents
PowerShell
231
star
36

ansible-plugin

Jenkins Ansible plugin
Java
223
star
37

workflow-cps-global-lib-plugin

Java
223
star
38

lib-file-leak-detector

Java agent that detects file handle leak
Java
217
star
39

bitbucket-branch-source-plugin

Bitbucket Branch Source Plugin
Java
213
star
40

hashicorp-vault-plugin

Jenkins plugin to populate environment variables from secrets stored in HashiCorp's Vault.
Java
212
star
41

remoting

Jenkins Remoting module
Java
212
star
42

workflow-aggregator-plugin

211
star
43

gerrit-trigger-plugin

Java
209
star
44

android-emulator-plugin

Android Emulator plugin for Jenkins
Java
207
star
45

docker-slaves-plugin

A Jenkins plugin to run builds inside Docker containers
Java
205
star
46

pipeline-stage-view-plugin

Visualizes Jenkins pipelines
JavaScript
204
star
47

jenkinsfile-runner-github-actions

Jenkins single-shot pipeline execution in a GitHub Action POC
Shell
198
star
48

github-branch-source-plugin

GitHub Branch Source Plugin
Java
193
star
49

amazon-ecs-plugin

Amazon EC2 Container Service Plugin for Jenkins
Java
193
star
50

trilead-ssh2

Patched trilead-ssh2 used in Jenkins
Java
193
star
51

cucumber-reports-plugin

Jenkins plugin to generate cucumber-jvm reports
Java
192
star
52

docker-build-publish-plugin

Java
192
star
53

performance-plugin

Performance Test Running and Reporting for Jenkins CI
Java
188
star
54

jira-plugin

Jenkins jira plugin
Java
169
star
55

gitea-plugin

This plugin provides the Jenkins integration for Gitea.
Java
168
star
56

embeddable-build-status-plugin

Embed build status of Jenkins jobs in web pages
Java
167
star
57

stashnotifier-plugin

A Jenkins Plugin to notify Atlassian Stash|Bitbucket of build results
Java
166
star
58

docker-ssh-agent

Docker image for Jenkins agents connected over SSH
PowerShell
162
star
59

workflow-cps-plugin

Java
160
star
60

http-request-plugin

This plugin does a request to an url with some parameters.
Java
154
star
61

stapler

Stapler web framework
Java
154
star
62

kubernetes-pipeline-plugin

Kubernetes Pipeline is Jenkins plugin which extends Jenkins Pipeline to provide native support for using Kubernetes pods, secrets and volumes to perform builds
Java
154
star
63

tfs-plugin

Jenkins tfs plugin
Java
145
star
64

jep

Jenkins Enhancement Proposals
Shell
144
star
65

kubernetes-cd-plugin

A Jenkins plugin to deploy to Kubernetes cluster
Java
140
star
66

jacoco-plugin

Jenkins JaCoCo Plugin
Java
139
star
67

qy-wechat-notification-plugin

企业微信Jenkins构建通知插件
Java
138
star
68

swarm-plugin

Jenkins swarm plugin
Java
134
star
69

git-client-plugin

Git client API for Jenkins plugins
Java
130
star
70

subversion-plugin

Jenkins subversion plugin
Java
126
star
71

dependency-check-plugin

Jenkins plugin for OWASP Dependency-Check. Inspects project components for known vulnerabilities (e.g. CVEs).
Java
126
star
72

role-strategy-plugin

Jenkins Role-Strategy plugin
Java
120
star
73

groovy-sandbox

(Deprecated) Compile-time transformer to run Groovy code in a restrictive sandbox
Java
120
star
74

jenkins-design-language

Styles, assets, and React classes for Jenkins Design Language
TypeScript
116
star
75

acceptance-test-harness

Acceptance tests cases for Jenkins and its plugins based on selenium and docker.
Java
116
star
76

scm-sync-configuration-plugin

Jenkins scm-sync-configuration plugin
Java
116
star
77

gitlab-branch-source-plugin

A Jenkins Plugin for GitLab Multibranch Pipeline jobs and Folder Organization
Java
115
star
78

git-parameter-plugin

Jenkins plugin for chosing Revision / Tag before build
Java
115
star
79

publish-over-ssh-plugin

Java
114
star
80

pipeline-as-yaml-plugin

Jenkins Pipeline As Yaml Plugin
Java
114
star
81

selenium-plugin

Jenkins selenium plugin
Java
112
star
82

code-coverage-api-plugin

Deprecated Jenkins Code Coverage Plugin
Java
111
star
83

docker-build-step-plugin

Java
111
star
84

jira-trigger-plugin

Triggers a build when a certain condition is matched in JIRA
Groovy
111
star
85

cobertura-plugin

Jenkins cobertura plugin
Java
110
star
86

gradle-plugin

Jenkins gradle plugin
Java
109
star
87

credentials-plugin

Provides Jenkins with extension points to securely store, manage, and bind credentials data to other Jenkins plugins, builds, pipelines, etc.
Java
107
star
88

jira-steps-plugin

Jenkins pipeline steps for integration with JIRA.
Java
104
star
89

artifactory-plugin

Jenkins artifactory plugin
Java
104
star
90

build-flow-plugin

A plugin to manage job orchestration
Groovy
103
star
91

throttle-concurrent-builds-plugin

Java
101
star
92

github-oauth-plugin

Jenkins authentication plugin using GitHub OAuth as the source.
Java
99
star
93

pipeline-graph-view-plugin

Java
99
star
94

promoted-builds-plugin

Jenkins Promoted Builds Plugin
Java
96
star
95

ssh-slaves-plugin

SSH Build Agents Plugin for Jenkins
Java
96
star
96

github-pr-coverage-status-plugin

Nice test coverage icon for your pull requests just from Jenkins
Java
93
star
97

jenkins-test-harness

Unit test framework for Jenkins core and its plugins
Java
92
star
98

opentelemetry-plugin

Monitor and observe Jenkins with OpenTelemetry.
Java
90
star
99

localization-zh-cn-plugin

Chinese Localization for Jenkins
HTML
89
star
100

workflow-remote-loader-plugin

Load Pipeline scripts from remote locations (e.g. Git) - replaced by Pipeline: Groovy Libraries plugin
Java
88
star