Run Playwright Tests in Jenkins: Jenkinsfile, Docker, Reports and Credentials

Many companies run their pipelines on Jenkins. In this lesson you will run a Playwright TypeScript suite in a Jenkins pipeline using the official Docker image, publish JUnit results and the HTML report, handle credentials, add parameters and schedules, and shard large suites.

---

🏗️ Why Jenkins?

Jenkins is the most widely used self-hosted CI server, especially in enterprises and service companies. If your team already builds and deploys with Jenkins, running Playwright there keeps everything in one pipeline. Playwright works well in Jenkins with a few Jenkins-specific settings you will learn here.

You need:

• A Jenkins server (or a local one) with the Pipeline, Git, JUnit and HTML Publisher plugins.
• Either Docker on the Jenkins agent (recommended) or Node.js installed on the agent.
• Your Playwright project in a Git repository.

---

⚙️ Step 1: Prepare the Playwright Config for Jenkins

Jenkins does not set the CI environment variable that the default config checks, so you will set it in the pipeline. Also add a JUnit reporter so Jenkins can show test results natively (reporters):

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 2 : undefined,
  reporter: [
    ['line'],
    ['html', { open: 'never' }],
    ['junit', { outputFile: 'results/junit.xml' }],
  ],
  use: {
    baseURL: process.env.BASE_URL ?? 'https://www.saucedemo.com',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
});

---

🐳 Step 2: Jenkinsfile with the Official Docker Image (Recommended)

Create a Jenkinsfile in the project root. The official Playwright image already contains Node.js, browsers and all system libraries:

pipeline {
  agent {
    docker {
      // Use the SAME version as @playwright/test in your package.json
      image 'mcr.microsoft.com/playwright:v1.xx.x-noble'
      args '--ipc=host'
    }
  }

  environment {
    CI = 'true'
    BASE_URL = 'https://www.saucedemo.com'
  }

  options {
    timeout(time: 60, unit: 'MINUTES')
  }

  stages {
    stage('Install') {
      steps {
        sh 'npm ci'
      }
    }
    stage('Test') {
      steps {
        sh 'npx playwright test'
      }
    }
  }

  post {
    always {
      junit allowEmptyResults: true, testResults: 'results/junit.xml'
      archiveArtifacts artifacts: 'playwright-report/**, test-results/**', allowEmptyArchive: true
      publishHTML(target: [
        allowMissing: true,
        alwaysLinkToLastBuild: true,
        keepAll: true,
        reportDir: 'playwright-report',
        reportFiles: 'index.html',
        reportName: 'Playwright Report'
      ])
    }
  }
}

What each part does:

Section	Purpose
agent { docker { ... } }	Runs the build inside the official Playwright container
args '--ipc=host'	Recommended for Chromium in Docker to avoid running out of shared memory
environment	Sets CI so the config uses CI settings, plus non-secret variables
npm ci	Installs exact dependency versions from package-lock.json
junit	Shows passed and failed tests and trends in Jenkins
archiveArtifacts	Keeps the HTML report, traces and screenshots for download
publishHTML	Adds a Playwright Report link to the build page

---

🖥️ Option: Agent Without Docker

If your agent cannot run Docker, install Node.js (for example with the NodeJS plugin) and the browsers in the pipeline:

pipeline {
  agent { label 'linux' }
  tools { nodejs 'node-lts' }          // name configured in Manage Jenkins, Tools
  environment { CI = 'true' }
  stages {
    stage('Install') {
      steps {
        sh 'npm ci'
        sh 'npx playwright install --with-deps'   // needs root or sudo on Linux for system libraries
      }
    }
    stage('Test') {
      steps { sh 'npx playwright test' }
    }
  }
}

On a Windows agent use bat instead of sh, for example bat 'npx playwright test', and npx playwright install without --with-deps.

---

🔐 Step 3: Credentials

Store passwords and tokens in Manage Jenkins, Credentials, then expose them only to the test step:

stage('Test') {
  steps {
    withCredentials([usernamePassword(credentialsId: 'qa-test-user',
                                      usernameVariable: 'TEST_USER',
                                      passwordVariable: 'TEST_PASSWORD')]) {
      sh 'npx playwright test'
    }
  }
}

Your tests read process.env.TEST_USER and process.env.TEST_PASSWORD (environment variables). Jenkins masks them in the console log.

---

🎛️ Step 4: Parameters, Tags and Schedules

Let people choose what to run, and schedule nightly regression:

pipeline {
  agent { docker { image 'mcr.microsoft.com/playwright:v1.xx.x-noble'; args '--ipc=host' } }
  parameters {
    choice(name: 'SUITE', choices: ['@smoke', '@regression', 'all'], description: 'Which tests to run')
    choice(name: 'BROWSER', choices: ['chromium', 'firefox', 'webkit'], description: 'Browser project')
  }
  triggers { cron('H 2 * * *') }       // nightly, around 02:00 server time
  environment { CI = 'true' }
  stages {
    stage('Install') { steps { sh 'npm ci' } }
    stage('Test') {
      steps {
        script {
          def grep = params.SUITE == 'all' ? '' : "--grep '" + params.SUITE + "'"
          sh "npx playwright test --project=" + params.BROWSER + " " + grep
        }
      }
    }
  }
}

Tags are explained in group, tag and filter tests.

---

⚡ Step 5: Parallel Shards in Jenkins

Split a large suite into parallel stages with --shard (parallel execution):

stage('Test') {
  parallel {
    stage('Shard 1') { steps { sh 'npx playwright test --shard=1/3 --reporter=blob' } }
    stage('Shard 2') { steps { sh 'npx playwright test --shard=2/3 --reporter=blob' } }
    stage('Shard 3') { steps { sh 'npx playwright test --shard=3/3 --reporter=blob' } }
  }
}

When shards run on different agents, stash each blob-report folder under a different name, unstash them into one folder, and run npx playwright merge-reports --reporter html <folder> in a final stage.

---

🧾 Viewing the HTML Report in Jenkins

Jenkins serves published HTML with a strict Content Security Policy that blocks JavaScript. Because the Playwright HTML report is a JavaScript application, the Playwright Report link may show a blank page. Options:

1. Download the archived playwright-report artifact and open it locally with npx playwright show-report <folder> (safest).
2. Ask your Jenkins administrator to relax the CSP for HTML reports. This affects security for all published reports, so it is an admin decision.
3. Rely on the JUnit test results in Jenkins for pass/fail and trends, and download traces only for failures (Trace Viewer).

---

✅ Jenkins Checklist

• Jenkinsfile committed to the repository (pipeline as code).
• Official Docker image with a tag matching @playwright/test, and --ipc=host.
• CI = 'true' set in environment.
• JUnit reporter for native results; HTML report and traces archived.
• Secrets only through Jenkins Credentials.
• Parameters for suite and browser; nightly cron trigger for regression.

---

📝 Assignment

1. Add junit and html reporters to your config and a Jenkinsfile using the official Docker image.
2. Create a Pipeline job in Jenkins pointing to your repository and run it.
3. Break a test on purpose and find it in the Jenkins Test Result view and in the archived report.
4. Move a password into Jenkins Credentials and use withCredentials.
5. Add SUITE and BROWSER parameters and run only @smoke in Firefox.
6. Add a nightly cron trigger.
7. Bonus: split the suite into three parallel shard stages.

---

❓ FAQ

🤔 How do I run Playwright tests in Jenkins?

Create a Jenkinsfile that runs npm ci and npx playwright test, preferably inside the official mcr.microsoft.com/playwright Docker image, and publish JUnit results and the HTML report in the post section.

🤔 Why does the Playwright HTML report show a blank page in Jenkins?

Jenkins’ Content Security Policy blocks the report’s JavaScript. Download the archived report and open it locally, or have an administrator adjust the CSP.

🤔 Why does my Playwright config ignore CI settings in Jenkins?

Jenkins does not set CI=true by default. Add CI = 'true' to the pipeline’s environment block.

🤔 Do I need Docker to run Playwright in Jenkins?

No, but it is recommended. Without Docker, install Node.js on the agent and run npx playwright install --with-deps, which needs system packages on Linux.

🤔 How do I pass secrets to Playwright tests in Jenkins?

Store them in Jenkins Credentials and wrap the test step in withCredentials; read them in tests through process.env.

---

🎯 Next Steps

• 🎭 Playwright with Docker and Kubernetes
• 🎭 Run Playwright Tests in GitHub Actions
• 🎭 Allure Report Integration
• 🎭 Playwright Tutorial with TypeScript