Running Parallel Test Stages in Docker Agents with Jenkins Declarative Pipelines

Desired Outcome

Configure a Jenkins Declarative Pipeline that pulls a Docker image once, runs multiple test stages in parallel inside separate containers, injects sensitive data via Jenkins credentials, and automatically cleans up all containers after the build.

Prerequisites

• Jenkins core 2.361 or newer.
• Docker Pipeline plugin ≥ 1.30.
• Docker daemon running on the Jenkins host with the user that runs the Jenkins agent having permission to start containers.
• Credentials stored in Jenkins (e.g., a secret text or username‑password) that will be bound to the container.
• Enough CPU/memory on the Jenkins master to host multiple concurrent containers.

Focused Procedure

1. Define the top‑level agent. The agent pulls a base image that contains the test tooling. The same image is reused in all branches unless overridden.

   pipeline {
     agent {
       docker {
         image 'myorg/test-base:latest'
         args '-u root:root'  // optional: run as root if needed
       }
     }
     stages {

2. Inject credentials into the container. Use the Credentials Binding plugin inside each parallel branch.

     stage('Parallel Tests') {
       parallel {
         "Unit Tests" : {
           steps {
             withCredentials([string(credentialsId: 'unit-test-token', variable: 'TOKEN')]) {
               sh 'run-unit-tests.sh $TOKEN'
             }
           }
         }
         "Integration Tests" : {
           steps {
             withCredentials([usernamePassword(credentialsId: 'int-test-creds', usernameVariable: 'USER', passwordVariable: 'PASS')]) {
               sh 'run-integration-tests.sh $USER $PASS'
             }
           }
         }
       }
     }
   }

3. Archive artifacts per branch. Each test script should write its results to a unique directory.

         steps {
           archiveArtifacts artifacts: 'reports/unit/**/*', fingerprint: true
         }

4. Aggregate results after parallel execution. A final stage collects all artifacts and publishes a consolidated report.

     stage('Aggregate Results') {
       steps {
         sh 'python aggregate.py'
         publishHTML([
           reportDir: 'aggregate-report',
           reportFiles: 'index.html',
           reportName: 'Test Summary'
         ])
       }
     }
   }
   

5. Ensure cleanup. The Docker Pipeline plugin removes the container automatically when the job ends unless reuseNode is set to true. Avoid setting reuseNode unless you explicitly manage container lifecycle.

Expected Checks

• Console output. Look for lines like Running on Docker for each parallel branch, confirming isolation.
• Container status. After the build, run docker ps -a on the Jenkins host. No lingering containers should appear.
• Pipeline graph. In Jenkins, open the Pipeline Steps tab. Parallel branches should display side‑by‑side.
• Credentials visibility. In the console, environment variables such as $TOKEN should not be printed. Verify by adding echo $TOKEN and ensuring the output is masked.
• Artifact existence. Navigate to the build's Artifacts page. Each test type should have its own folder.

Recovery Options

• Agent start failure. If the Docker image cannot be pulled, the build fails immediately. Check the Docker daemon logs and verify the image name and registry credentials.
• Resource exhaustion. If the master runs out of memory or CPU, parallel stages may stall. Scale the master or reduce the number of parallel branches.
• Orphaned containers. In rare cases, a container may persist. Run docker rm -f $(docker ps -aq) on the Jenkins host after ensuring no builds are running.
• Credential mis‑binding. If a credential is missing, the stage will fail with a clear message. Verify the credential ID in the Jenkins Credentials store.

Practical Verification Checklist

Step	What to Verify
1. Build Trigger	Console shows Running on Docker for each branch.
2. Resource Cleanup	No containers listed after docker ps -a.
3. Artifact Archiving	Artifacts page contains reports/unit and reports/integration.
4. Credential Masking	No plain text credentials in console logs.

Limitations and Caveats

• Docker must be installed with the same user that runs the Jenkins agent; otherwise the agent cannot start containers.
• Large images can increase the first build time; consider pre‑pulling or using a local registry.
• Enabling reuseNode keeps containers alive across builds, which can lead to stale data if not cleaned manually.
• Parallel stages increase concurrent container usage; monitor host resources.