jenkinsfile-test-stages
Configures Jenkins declarative pipeline test stages - `Jenkinsfile` with stages, parallel + per-agent execution, post-actions (always / failure / success), pipeline-junit-plugin for test reports, lockable resources for shared infra. Use for Jenkins-based CI (common in enterprise / regulated environments).
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:
When to use
For new projects in 2026+: GitHub Actions / GitLab CI offer better managed-runner experiences. Jenkins shines in self-hosted
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: 'team@example.com', 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). |