jenkinsfile-test-stages

jenkinsfile-test-stages

Overview

Jenkins Declarative Pipeline (introduced 2017) is the modern Jenkinsfile syntax - replaces older Scripted Pipeline for most use cases.

A Jenkinsfile defines:

• Pipeline - top-level container.
• Agent - where stages run (any agent / specific node / Docker container).
• Stages - sequential or parallel phases.
• Steps - commands within a stage.
• Post - actions after stages (always / success / failure / unstable / changed).

When to use

• Enterprise / regulated environments using Jenkins.
• Existing Jenkins infrastructure; migration to GitHub Actions / GitLab CI prohibitive.
• Self-hosted CI / specialized hardware needs (GPU, specialized drivers).

For new projects in 2026+: GitHub Actions / GitLab CI offer better managed-runner experiences. Jenkins shines in self-hosted

• plugin-rich environments.

Step 1 - Basic Jenkinsfile

// Jenkinsfile
pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                sh 'npm ci'
            }
        }
        stage('Test') {
            steps {
                sh 'npm test'
            }
        }
    }
}

agent any runs on any available executor; pin via agent { label 'linux' } or agent { docker { image 'node:22' } }.

Step 2 - Docker agent

pipeline {
    agent {
        docker {
            image 'node:22'
            args '-v /tmp:/tmp'
        }
    }

    stages {
        stage('Test') {
            steps {
                sh 'npm ci && npm test'
            }
        }
    }
}

Docker agents provide reproducibility - same Node version on every run.

Step 3 - Parallel stages

pipeline {
    agent any

    stages {
        stage('Tests') {
            parallel {
                stage('Unit') {
                    steps { sh 'npm test' }
                }
                stage('Integration') {
                    steps { sh 'npm run test:integration' }
                }
                stage('E2E') {
                    agent {
                        docker { image 'mcr.microsoft.com/playwright:v1.50.0-noble' }
                    }
                    steps { sh 'npx playwright test' }
                }
            }
        }
    }
}

Parallel stages can have different agents - useful when E2E needs a Playwright-equipped image.

Step 4 - Matrix builds (Jenkins 2.302+)

pipeline {
    agent none

    stages {
        stage('Test matrix') {
            matrix {
                axes {
                    axis {
                        name 'OS'
                        values 'linux', 'macos', 'windows'
                    }
                    axis {
                        name 'NODE_VERSION'
                        values '20', '22'
                    }
                }
                stages {
                    stage('Test') {
                        agent { label "${OS}" }
                        steps {
                            sh 'npm ci && npm test'
                        }
                    }
                }
            }
        }
    }
}

Matrix runs all OS × Node combinations in parallel.

Step 5 - Post actions

pipeline {
    agent any

    stages {
        stage('Test') {
            steps {
                sh 'npm test'
            }
        }
    }

    post {
        always {
            // Always run — even on failure
            junit 'reports/junit/*.xml'
            archiveArtifacts artifacts: 'coverage/**', allowEmptyArchive: true
        }
        success {
            slackSend(channel: '#ci', message: "✅ Build ${env.BUILD_NUMBER} passed")
        }
        failure {
            slackSend(channel: '#ci', message: "❌ Build ${env.BUILD_NUMBER} failed: ${env.BUILD_URL}")
        }
        unstable {
            // E.g., tests passed but with warnings
            mail to: '[email protected]', subject: "Build ${env.BUILD_NUMBER} unstable"
        }
    }
}

post { always {} } runs on any outcome - essential for artifact upload + notifications.

The junit '...' step (from JUnit Plugin) parses XML and renders results in Jenkins UI.

Step 6 - Lockable resources

pipeline {
    agent any

    stages {
        stage('Integration') {
            steps {
                lock(resource: 'shared-test-database') {
                    sh 'npm run test:integration'
                }
            }
        }
    }
}

lock(...) uses the Lockable Resources Plugin to serialize access to shared resources (test DB, license-locked tool, etc.).

Step 7 - Environment + credentials

pipeline {
    agent any

    environment {
        CI = 'true'
        NODE_ENV = 'test'
    }

    stages {
        stage('Test') {
            steps {
                withCredentials([string(credentialsId: 'npm-auth-token', variable: 'NODE_AUTH_TOKEN')]) {
                    sh 'npm ci && npm test'
                }
            }
        }
    }
}

withCredentials([...]) masks secrets in build logs.

Step 8 - Multi-branch + scheduled

pipeline {
    agent any

    triggers {
        cron('0 4 * * *')   // daily at 4 AM
        pollSCM('*/15 * * * *')   // poll every 15 min (or use webhook)
    }

    options {
        timeout(time: 30, unit: 'MINUTES')
        timestamps()
        ansiColor('xterm')
        buildDiscarder(logRotator(numToKeepStr: '20'))
    }

    stages { /* ... */ }
}

Per-branch behavior via Multibranch Pipeline job type (separate config in Jenkins UI).

Step 9 - When to retry

stage('Test') {
    steps {
        retry(2) {
            sh 'npm test'
        }
    }
}

Use sparingly - retries hide flake. Prefer flaky-test-quarantine.

Anti-patterns

Anti-pattern	Why it fails	Fix
Scripted pipeline for new code	Declarative is the standard; better tooling support.	Declarative Pipeline (Step 1).
Plaintext credentials in Jenkinsfile	Secret leak.	withCredentials({...}) (Step 7).
No post { always {} } for artifact upload	Failure investigation incomplete.	Always upload (Step 5).
Single-agent pipeline for parallel work	No parallelism; slow.	Parallel stages (Step 3).
Missing timeout	Hung jobs consume executors indefinitely.	options { timeout(...) } (Step 8).
Skipping agent { docker {...}}	Inconsistent runtime per agent; hard to reproduce.	Docker agents (Step 2).

Limitations

• Plugin-heavy ecosystem. Updates can break things; pin versions.
• Self-hosted infra cost. Manage Jenkins controller + agents.
• Slower modernization. Jenkins evolves; modern features (matrix, declarative) require version bumps.
• YAML / Groovy mix. Jenkinsfile is Groovy DSL; some teams prefer YAML.

References

• Jenkins Declarative Pipeline at jenkins.io/doc/book/pipeline/.
• github-actions-test-jobs, gitlab-ci-test-jobs, circleci-test-configs - alternatives.
• junit-xml-analysis - JUnit XML parser.