# jenkinsci/jenkinspipelineunit architecture

> Architecture diagram of the GitHub repository jenkinsci/jenkinspipelineunit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jenkinsci/jenkinspipelineunit
- Repository: https://github.com/jenkinsci/jenkinspipelineunit

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Modules
    subgraph "Core Library Modules"
        direction TB
        PTH["PipelineTestHelper"]:::core
        IGC["InterceptingGCL"]:::core
        LCL["LibClassLoader"]:::core
        MC["MethodCall"]:::core
        MS["MethodSignature"]:::core
        VM["VerificationException"]:::core
        DM["DockerMock"]:::core
    end

    %% Test Base Classes
    subgraph "Test Base Classes"
        direction TB
        BPT["BasePipelineTest"]:::test
        BRT["BaseRegressionTest"]:::test
        DPT["DeclarativePipelineTest"]:::test
        BPTCPS["BasePipelineTestCPS"]:::test
        BRTCPS["BaseRegressionTestCPS"]:::test
    end

    %% CPS Support
    subgraph "CPS Support"
        direction TB
        PTHCPS["PipelineTestHelperCPS"]:::core
        MPSCPS["MockPipelineScriptCPS"]:::core
        MCLOS["MockClosure"]:::core
    end

    %% Script Execution Engine
    subgraph "Script Execution Engine"
        direction TB
        MPS["MockPipelineScript"]:::core
    end

    %% Global Lib Subsystem
    subgraph "Global Lib Subsystem"
        direction TB
        LC["LibraryConfiguration"]:::core
        SR["SourceRetriever"]:::core
        GS["GitSource"]:::core
        LS["LocalSource"]:::core
        PS["ProjectSource"]:::core
        LL["LibraryLoader"]:::core
        LR["LibraryRecord"]:::core
        LB["Library"]:::core
        LAT["LibraryAnnotationTransformer"]:::core
    end

    %% Declarative Model
    subgraph "Declarative Model"
        direction TB
        DP["DeclarativePipeline"]:::core
        DD["Declarative DSL Declarations"]:::core
        DH["ComparatorEnum & ObjectUtils"]:::core
    end

    %% Test Suites
    subgraph "Test Suites"
        direction TB
        TS1["Groovy Tests"]:::test
        TS2["Unit Tests"]:::test
        TRF["Regression Test Resources"]:::test
        JFL["Jenkinsfile Loader Tests"]:::test
        JBT["Job Definition Tests"]:::test
        SLT["Sample Shared Libs"]:::test
    end

    %% Build & CI Infrastructure
    subgraph "Build & CI Infrastructure"
        direction TB
        GB["Gradle Build"]:::infra
        GH["GitHub Actions"]:::infra
        JENK["Jenkins CI Pipeline"]:::infra
        PD["Publish to Maven Repo"]:::infra
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        EXGIT["Git Repository"]:::external
        MAVEN["Maven Repo"]:::external
        JDSL["Jenkins Pipeline DSL"]:::external
    end

    %% Relationships
    TS1 -->|extends| BPT
    TS1 -->|extends| BRT
    TS1 -->|extends| DPT
    TS1 -->|extends| BPTCPS
    TS1 -->|extends| BRTCPS

    BPT -->|uses| PTH
    BRT -->|uses| PTH
    DPT -->|uses| PTH
    BPTCPS -->|uses| PTHCPS
    BRTCPS -->|uses| PTHCPS

    PTH -->|executes| MPS
    PTHCPS -->|executes| MPSCPS

    MPS -->|intercepts via| IGC
    MPSCPS -->|uses| MCLOS

    IGC -->|loads| LCL
    MPS -->|records| MC
    MC -->|has signature| MS

    PTH -->|asserts| VM
    PTH -->|provides mock| DM

    PTH -->|registerSharedLibrary| LC
    LC -->|creates| SR
    SR -->|impl| GS
    SR -->|impl| LS
    SR -->|impl| PS
    LC -->|uses| LL
    LL -->|tracks| LR
    LL -->|manages| LB
    LL -->|applies| LAT

    DPT -->|models| DP
    DP -->|uses| DD
    DP -->|uses| DH

    PTH -->|runs| TS2

    GB -->|runs tests| TS1
    GH -->|triggers| GB
    JENK -->|triggers| GB
    GB -->|publishes| PD
    PD -->|to| MAVEN

    SR -->|fetches from| EXGIT

    JDSL -->|mocked by| PTH

    %% Click Events
    click PTH "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/PipelineTestHelper.groovy"
    click BPT "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/BasePipelineTest.groovy"
    click BRT "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/BaseRegressionTest.groovy"
    click DPT "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/declarative/DeclarativePipelineTest.groovy"
    click BPTCPS "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/cps/BasePipelineTestCPS.groovy"
    click BRTCPS "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/cps/BaseRegressionTestCPS.groovy"
    click PTHCPS "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/cps/PipelineTestHelperCPS.groovy"
    click LC "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/global/lib/LibraryConfiguration.groovy"
    click SR "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/global/lib/SourceRetriever.groovy"
    click GS "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/global/lib/GitSource.groovy"
    click LS "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/global/lib/LocalSource.groovy"
    click PS "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/global/lib/ProjectSource.groovy"
    click LL "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/global/lib/LibraryLoader.groovy"
    click LR "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/global/lib/LibraryRecord.groovy"
    click LB "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/global/lib/Library.groovy"
    click LAT "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/global/lib/LibraryAnnotationTransformer.groovy"
    click MPS "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/MockPipelineScript.groovy"
    click MPSCPS "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/cps/MockPipelineScriptCPS.groovy"
    click IGC "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/InterceptingGCL.groovy"
    click LCL "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/LibClassLoader.groovy"
    click MC "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/MethodCall.groovy"
    click MS "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/MethodSignature.groovy"
    click VM "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/VerificationException.groovy"
    click DM "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/DockerMock.groovy"
    click MCLOS "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/cps/MockClosure.groovy"
    click DP "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/src/main/groovy/com/lesfurets/jenkins/unit/declarative/DeclarativePipeline.groovy"
    click DD "https://github.com/jenkinsci/jenkinspipelineunit/tree/master/src/main/groovy/com/lesfurets/jenkins/unit/declarative"
    click TS1 "https://github.com/jenkinsci/jenkinspipelineunit/tree/master/src/test/groovy/com/lesfurets/jenkins/"
    click TS2 "https://github.com/jenkinsci/jenkinspipelineunit/tree/master/src/test/groovy/com/lesfurets/jenkins/unit/"
    click JFL "https://github.com/jenkinsci/jenkinspipelineunit/tree/master/src/test/jenkins/jenkinsfiles/"
    click JBT "https://github.com/jenkinsci/jenkinspipelineunit/tree/master/src/test/jenkins/job/"
    click TRF "https://github.com/jenkinsci/jenkinspipelineunit/tree/master/src/test/resources/callstacks/"
    click SLT "https://github.com/jenkinsci/jenkinspipelineunit/tree/master/src/test/resources/libs/"
    click GB "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/build.gradle"
    click GH "https://github.com/jenkinsci/jenkinspipelineunit/blob/master/.github/workflows/test.yml"
    click JENK "https://github.com/jenkinsci/jenkinspipelineunit/tree/master/Jenkinsfile"
    click PD "https://github.com/jenkinsci/jenkinspipelineunit/tree/master/repo.jenkins-ci.org/releases"

    %% Styles
    classDef core fill:#c3d9ff,stroke:#0366d6,stroke-width:1px
    classDef test fill:#d4fde1,stroke:#28a745,stroke-width:1px
    classDef infra fill:#ffe5b4,stroke:#f66a0a,stroke-width:1px
    classDef external fill:#e1e4e8,stroke:#6a737d,stroke-width:1px
```
