How jenkinsci/jenkinspipelineunit works
Project Type and Purpose
• This is an open-source testing framework (library) for unit-testing Jenkins pipelines in Groovy.
• It provides mocks for Jenkins steps, a helper to load and execute pipeline scripts, and assertions on call stacks and pipeline status.
Main Architectural Components
a. Core Library Modules (src/main/groovy/com/lesfurets/jenkins)
• PipelineTestHelper – central class that mocks steps, records calls, holds configuration
• BasePipelineTest, BaseRegressionTest, BasePipelineTestCPS, DeclarativePipelineTest – JUnit-style base classes that configure the helper for different testing modes (scripted, declarative, CPS)
• global.lib – library loader abstractions (LibraryConfiguration, SourceRetriever, GitSource, LocalSource, ProjectSource, LibraryLoader)
• unit/… – support code for unit tests (mocking CPS, intercepting method calls, managing closures)
b. Test Suite (src/test)
• Groovy and Java test cases organized by feature: core pipeline tests, unit/CPS tests, declarative tests, shared-library tests
• Test resources (jenkinsfiles, job definitions, callstack references, sample libraries)
c. Build & CI Infrastructure
• Gradle build (build.gradle, gradle wrapper)
• GitHub Actions & Jenkinsfile for CI pipelines
• Release Drafter, Dependabot configuration, publishing to Jenkins CI Maven repo
Component Relationships and Data Flow
1. A user test (e.g. a class extending BasePipelineTest) → invokes super.setUp() → configures PipelineTestHelper
2. Test calls runScript()/loadScript() → PipelineTestHelper locates and parses Jenkinsfile or .jenkins script → transforms it into a Groovy script
3. PipelineTestHelper executes the script in a sandboxed environment → intercepts calls to pipeline steps (sh, node, stage, load, library, etc.)
4. Each step invocation is recorded in a call-stack log; mocks return preconfigured results
5. Test assertions inspect helper.callStack, currentBuild.result, or compare against saved callstack resources for regression testing
6. For shared-library tests, helper.registerSharedLibrary builds a LibraryConfiguration and SourceRetriever → PipelineTestHelper clones or loads library files → makes vars and classes available to the test execution
Architectural Patterns and Principles
• Dependency Injection: test code injects environment variables, parameters, custom mocks via helper registers
• Strategy Pattern: SourceRetriever interface with multiple implementations (GitSource, LocalSource, ProjectSource)
• Template Method: BasePipelineTest provides a setup/template for specific test variants (CPS, declarative)
• Facade: PipelineTestHelper provides a unified façade over low-level mocking and execution details
• Record & Replay: call-stack recorder to capture method calls and support regression assertions
Technologies, Frameworks, and External Services
• Groovy, JUnit (or Spock), Gradle, Java 17
• Jenkins Pipeline DSL (mocked)
• GitHub Actions, Jenkins CI (for building, testing, and releasing)
• Maven-style artifact repository at repo.jenkins-ci.org/releases