Jenkins pipeline for Playwright: Step by Step (2026)

TL;DR

A dependable Jenkins pipeline checks out a locked Playwright project, runs it in a compatible Linux environment, publishes JUnit results, and archives Playwright diagnostics. The Jenkinsfile below adds timeouts, retry-safe reporting, sharding options, secrets, and clear failure behavior.

Key Takeaways

• Pin Node, Playwright, and the browser image through source control so every build uses the same test runtime.
• Use npm ci and a committed lockfile, never an unpinned dependency install in the pipeline.
• Publish JUnit results and archive the Playwright HTML report, traces, screenshots, and videos after every run.
• Start with Playwright worker parallelism, then add Jenkins stage sharding only when the suite is large enough.
• Keep retries low and preserve first-retry traces so failures remain diagnosable instead of being hidden.
• Inject credentials through Jenkins bindings and prevent secrets from entering configuration files or artifacts.

A Jenkins pipeline for Playwright should produce the same result on a clean agent that a developer gets from a clean local checkout. The dependable pattern is simple: pin the runtime, install from the lockfile, install compatible browsers, run tests with CI-aware settings, publish machine-readable results, and preserve diagnostics even when the test command fails.

This guide builds that pattern step by step. It uses a declarative Jenkinsfile, Playwright Test for TypeScript, JUnit reporting, the Playwright HTML report, and optional Docker isolation. It also explains the operational decisions that separate a demo pipeline from one a QA team can trust.

TL;DR

The shortest working flow is checkout -> npm ci -> npx playwright install --with-deps -> npx playwright test -> publish reports. Production pipelines add pinning, timeouts, concurrency controls, cleanup, and branch-aware scope.

1. What a Jenkins pipeline for Playwright must control

A browser test depends on more than test code. It depends on Node.js, npm resolution, Playwright Test, browser binaries, Linux libraries, fonts, locale, time zone, network access, test data, and application state. If Jenkins leaves those inputs implicit, failures become agent-specific and difficult to reproduce.

Treat the pipeline as an executable environment contract. The repository should contain package.json, package-lock.json, playwright.config.ts, tests, and the Jenkinsfile. The Jenkins controller should schedule work, while disposable agents execute it. A newly created agent must not depend on browser files or node modules left by an earlier build.

The pipeline also owns evidence. Jenkins needs a JUnit XML file to understand passed, failed, and skipped tests. Engineers need the HTML report, traces, screenshots, and possibly videos to investigate. Those files must be published from a post { always { ... } } block because a failed test stage is exactly when evidence matters most.

Finally, define failure semantics. A failed assertion should make the build fail. An empty suite should usually fail through Playwright's normal behavior. A report publishing problem should be visible, but allowEmptyResults and allowEmptyArchive can keep the post action from replacing the original failure with a secondary error.

2. Prepare a reproducible Playwright project

Start with a normal Playwright Test project and commit the lockfile. The following commands create the relevant dependencies. Run them once during project setup, not on every Jenkins build:

npm init -y
npm install --save-dev @playwright/test typescript
npx playwright install

Add stable scripts to package.json so local and CI execution use the same entry point:

{
  "scripts": {
    "test:e2e": "playwright test",
    "test:e2e:chromium": "playwright test --project=chromium",
    "test:e2e:smoke": "playwright test --grep @smoke",
    "report:e2e": "playwright show-report"
  },
  "devDependencies": {
    "@playwright/test": "^1.52.0",
    "typescript": "^5.8.0"
  }
}

The versions are illustrative valid baselines. In a real repository, commit the exact versions selected by your team through package-lock.json, and update them with a reviewed dependency change. The browser build installed by Playwright is tied to the Playwright package version, so package and browser lifecycle should move together.

Create at least one small smoke test that proves the runner works independently of your full environment:

import { test, expect } from '@playwright/test';

test('QAJobFit resources page has a heading @smoke', async ({ page }) => {
  await page.goto('/resources');
  await expect(page.getByRole('heading', { level: 1 })).toBeVisible();
});

If locator strategy is still evolving, the Playwright getByTestId guide explains when a stable test contract is preferable to CSS selectors.

3. Configure Playwright for Jenkins CI

Keep CI behavior in playwright.config.ts, not scattered across shell flags. Playwright exposes process.env.CI, reporters, retries, workers, output directories, and artifact policies through supported configuration APIs:

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: Boolean(process.env.CI),
  retries: process.env.CI ? 1 : 0,
  workers: process.env.CI ? 2 : undefined,
  timeout: 30_000,
  expect: {
    timeout: 7_000
  },
  reporter: [
    ['line'],
    ['junit', { outputFile: 'test-results/junit.xml' }],
    ['html', { outputFolder: 'playwright-report', open: 'never' }]
  ],
  use: {
    baseURL: process.env.BASE_URL ?? 'http://127.0.0.1:4173',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure'
  },
  outputDir: 'test-results/artifacts',
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] }
    }
  ]
});

forbidOnly prevents an accidentally committed test.only from turning a full build into a misleading partial run. Two CI workers are a conservative default, not a universal optimum. Increase them only after observing CPU, memory, application capacity, and execution time.

The JUnit reporter gives Jenkins structured results. The HTML reporter is the richer human report. Both can run simultaneously. Playwright attachments are stored under the configured output directory and linked from the HTML report when the directory structure is preserved.

Environment-specific values belong in environment variables. Do not create separate config files that gradually diverge unless environments truly require different test topology.

4. Build the first runnable Jenkinsfile

This declarative pipeline runs on a Jenkins agent with Node.js and permission to install the required Linux browser packages. It is intentionally explicit:

pipeline {
  agent { label 'linux-node22' }

  options {
    timestamps()
    disableConcurrentBuilds(abortPrevious: true)
    timeout(time: 45, unit: 'MINUTES')
    buildDiscarder(logRotator(numToKeepStr: '30'))
  }

  environment {
    CI = 'true'
    BASE_URL = 'https://staging.example.com'
    PLAYWRIGHT_BROWSERS_PATH = "${WORKSPACE}/.cache/ms-playwright"
  }

  stages {
    stage('Checkout') {
      steps {
        checkout scm
      }
    }

    stage('Install dependencies') {
      steps {
        sh 'npm ci'
        sh 'npx playwright install --with-deps chromium'
      }
    }

    stage('Run Playwright') {
      steps {
        sh 'npm run test:e2e:chromium'
      }
    }
  }

  post {
    always {
      junit testResults: 'test-results/junit.xml',
        allowEmptyResults: true,
        keepLongStdio: true
      archiveArtifacts artifacts: 'playwright-report/**,test-results/**',
        allowEmptyArchive: true,
        fingerprint: false
    }
    cleanup {
      deleteDir()
    }
  }
}

Jenkins interpolates WORKSPACE in the Groovy environment value. The shell receives ordinary strings, so there is no need to add extra quoting layers. disableConcurrentBuilds(abortPrevious: true) is appropriate for a staging pipeline where only the newest commit matters. Remove abortPrevious if every revision must complete.

The --with-deps flag installs operating system dependencies and browser binaries. It generally requires an agent image and user permissions designed for that operation. If your Jenkins agents cannot install packages, use the container approach in the next section.

5. Use Docker for a Playwright Jenkins pipeline

The official Playwright container includes browsers and their Linux dependencies. Its image tag must match the Playwright package version in the repository. A mismatch can produce a message that the expected browser executable is missing.

A Docker-based declarative pipeline looks like this:

pipeline {
  agent {
    docker {
      image 'mcr.microsoft.com/playwright:v1.52.0-noble'
      args '--ipc=host'
    }
  }

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

  environment {
    CI = 'true'
    BASE_URL = 'https://staging.example.com'
  }

  stages {
    stage('Checkout') {
      steps {
        checkout scm
      }
    }

    stage('Install locked packages') {
      steps {
        sh 'npm ci'
      }
    }

    stage('Test') {
      steps {
        sh 'npx playwright test --project=chromium'
      }
    }
  }

  post {
    always {
      junit testResults: 'test-results/junit.xml', allowEmptyResults: true
      archiveArtifacts artifacts: 'playwright-report/**,test-results/**',
        allowEmptyArchive: true
    }
  }
}

This syntax requires Jenkins Docker Pipeline support and a worker that can run Docker. The --ipc=host option is recommended for Chromium stability in containerized Linux environments with constrained shared memory. It is not a substitute for adequate memory limits.

Update the container tag and @playwright/test together. A practical dependency update changes both in one pull request, runs the smoke suite, then runs the full regression suite. Never use a floating latest image in a production test pipeline because the same Git revision could execute against different browser builds on different days.

6. Publish JUnit, HTML, traces, screenshots, and videos

A useful Jenkins build answers two questions: which test failed, and what happened in the browser. JUnit handles the first. Playwright artifacts handle the second.

The junit step should point to the same path configured in the Playwright reporter. Jenkins then marks test failures, shows trends, and attaches cases to the build. Keep the XML outside outputDir if your cleanup or blob merging process replaces artifact directories.

The HTML report is a static directory. archiveArtifacts stores it, although opening archived HTML can be less convenient than publishing it with the Jenkins HTML Publisher plugin. If that plugin is approved, add:

post {
  always {
    publishHTML(target: [
      reportDir: 'playwright-report',
      reportFiles: 'index.html',
      reportName: 'Playwright HTML Report',
      keepAll: true,
      alwaysLinkToLastBuild: true,
      allowMissing: true
    ])
  }
}

Do not expose reports from sensitive test environments without reviewing their contents. Traces can contain URLs, DOM snapshots, request metadata, console messages, and screenshots. Videos can capture personal or confidential data. Apply Jenkins authorization, artifact retention, and data masking as seriously as you would for application logs.

For a deep explanation of report tradeoffs, see Allure vs Extent Reports. Playwright HTML is often sufficient for a single framework, while centralized reporting may help cross-framework organizations.

7. Manage credentials and environment configuration safely

Jenkins credentials binding injects secrets only for the scope of the protected block. Store a staging username/password pair as a Jenkins username-password credential, then bind it without printing values:

stage('Authenticated tests') {
  steps {
    withCredentials([
      usernamePassword(
        credentialsId: 'staging-e2e-user',
        usernameVariable: 'E2E_USERNAME',
        passwordVariable: 'E2E_PASSWORD'
      ),
      string(
        credentialsId: 'staging-api-token',
        variable: 'E2E_API_TOKEN'
      )
    ]) {
      sh '''
        set +x
        npx playwright test --project=chromium
      '''
    }
  }
}

Read those values through process.env inside tests or a setup project. Fail early with a clear message when a required variable is absent, but never include the value in the message:

const username = process.env.E2E_USERNAME;
const password = process.env.E2E_PASSWORD;

if (!username || !password) {
  throw new Error('E2E_USERNAME and E2E_PASSWORD are required');
}

Masking is a safeguard, not permission to echo secrets. Avoid shell tracing, URL query parameters containing tokens, screenshots of password managers, and JSON storage-state files in archived directories. If you create Playwright authentication state, write it under a dedicated ignored directory and archive neither that directory nor raw tokens.

Keep non-secret configuration such as BASE_URL visible and branch-aware. Production execution should require an explicit parameter and authorization, not be inferred from a branch name alone.

8. Start the application and wait for readiness

A pipeline that tests the deployed staging site only needs a reachable BASE_URL. A pipeline testing the current web application revision must build and start that application before Playwright.

Playwright's webServer option is the cleanest approach for one local service:

export default defineConfig({
  webServer: {
    command: 'npm run preview -- --host 0.0.0.0',
    url: 'http://127.0.0.1:4173',
    reuseExistingServer: !process.env.CI,
    timeout: 120_000
  },
  use: {
    baseURL: 'http://127.0.0.1:4173'
  }
});

The Jenkins stages can then build and test:

stage('Build application') {
  steps {
    sh 'npm run build'
  }
}

stage('Run browser tests') {
  steps {
    sh 'npx playwright test'
  }
}

Playwright starts the command, polls the configured URL, runs tests after readiness, and terminates the child process. This is safer than npm run preview & sleep 10, which assumes a fixed boot time and can leave a process behind.

For multiple services, use a Jenkins-managed Docker Compose environment or an ephemeral test namespace. Add a real health endpoint that verifies required dependencies, not just an open TCP port. Record deployment identifiers in the build description so a failure can be tied to the exact application revision.

9. Add branches, parameters, and suite selection

Not every event needs the same suite. Pull requests often need Chromium smoke tests, while the main branch or a nightly schedule runs cross-browser regression. Make the distinction explicit and keep suite tags in test titles or annotations.

A parameterized stage can safely choose a supported script:

parameters {
  choice(
    name: 'SUITE',
    choices: ['smoke', 'regression'],
    description: 'Playwright suite to run'
  )
}

stage('Run selected suite') {
  steps {
    script {
      if (params.SUITE == 'smoke') {
        sh 'npx playwright test --grep @smoke --project=chromium'
      } else {
        sh 'npx playwright test --project=chromium'
      }
    }
  }
}

Do not concatenate arbitrary parameter text into a shell command. A fixed allowlist avoids command injection and prevents spelling mistakes from producing empty or misleading runs.

Declarative when conditions can add browser coverage on the main branch:

stage('Cross-browser regression') {
  when {
    branch 'main'
  }
  steps {
    sh 'npx playwright test'
  }
}

Multibranch Jenkins jobs expose branch context most reliably. For manually created pipeline jobs, verify which environment variables your plugins provide. Keep the default pull request check fast enough to protect developer feedback, but do not label a small smoke set as full regression.

10. Scale with workers and Jenkins sharding

Playwright workers run test files in parallel inside one process tree. Jenkins can also run shards on separate executors. Use one layer deliberately before combining both.

For four shards, use a Jenkins matrix axis:

stage('Sharded regression') {
  matrix {
    axes {
      axis {
        name 'SHARD'
        values '1', '2', '3', '4'
      }
    }
    stages {
      stage('Run shard') {
        steps {
          sh "npx playwright test --shard=${env.SHARD}/4"
        }
      }
    }
  }
}

In Groovy-heavy Jenkinsfiles, environment interpolation and shell quoting deserve a dry run. Another readable option is a scripted loop that creates parallel branches with fixed shard values.

If you need one combined HTML report, configure Playwright's blob reporter on shards, preserve each blob report under a unique path, collect them into one workspace, then run npx playwright merge-reports --reporter html <blob-directory>. The transfer mechanism depends on Jenkins topology, commonly stash and unstash. Test IDs and repository content must match across shards.

Sharding cannot repair shared accounts or order-dependent data. Isolate data first, then add capacity.

11. Control flaky tests without hiding failures

A retry is a diagnostic tool, not a pass-generation mechanism. With retries: 1, Playwright classifies a test that fails first and passes on retry as flaky. That signal should be tracked and assigned, not ignored because the build eventually turns green.

Common sources of CI-only instability include reused accounts, non-unique data, animations, service throttling, undersized agents, external dependencies, and assertions made before the system reaches the expected state. Prefer web-first assertions such as await expect(locator).toBeVisible(); they retry until the assertion timeout. Avoid fixed sleeps.

Use testInfo to make data unique per worker:

import { test, expect } from '@playwright/test';

test('creates an isolated profile', async ({ page }, testInfo) => {
  const email = `pw-${testInfo.workerIndex}-${Date.now()}@example.test`;

  await page.goto('/profiles/new');
  await page.getByLabel('Email').fill(email);
  await page.getByRole('button', { name: 'Create profile' }).click();

  await expect(page.getByText(email)).toBeVisible();
});

A quarantine tag may be necessary during incident response, but it needs an owner, issue, and expiry. If a pipeline routinely reruns the entire suite until green, it destroys evidence about real reliability.

The Playwright timeout troubleshooting guide is useful when a failure is caused by waiting behavior rather than Jenkins itself.

12. Harden the Jenkins pipeline for Playwright

Production hardening is mostly about bounded resource use and explainable state. Add a pipeline timeout so a stuck browser cannot occupy an executor indefinitely. Add build retention because traces and videos are large. Delete the workspace after artifacts are safely archived. Prevent overlapping builds when they compete for the same staging data.

Use separate credentials and isolated environments for pull requests from untrusted forks. Jenkinsfile changes are code execution on agents, so never expose protected credentials to an unreviewed pipeline definition. Configure trusted branch policies in Jenkins and your source control integration.

Cache carefully. Caching node_modules across revisions is risky because native modules and dependency trees can drift. npm ci is designed to create a clean install. Caching the npm download cache can help without reusing an installed tree. Browser caching helps on non-container agents, but key it by operating system, architecture, and the Playwright package version.

Add observability that aids triage: timestamps, application revision, environment name, selected suite, browser project, shard, and agent label. Avoid dumping every environment variable because that can expose secrets. A concise build description is often enough.

Finally, rehearse failure paths. Intentionally fail one assertion and confirm that Jenkins is red, the JUnit case appears, the HTML report opens, the trace is retained under the configured policy, and cleanup still runs.

13. Troubleshoot common Jenkins and Playwright failures

When Jenkins says the browser executable does not exist, first compare the @playwright/test version in the lockfile with the Docker image tag or installed browser cache. Run npx playwright install chromium in the same runtime and user context as the tests.

If Chromium crashes in Docker, review memory and shared memory. Use --ipc=host where permitted, avoid dozens of workers on a small agent, and inspect browser stderr in Playwright output. Do not immediately add launch flags such as --no-sandbox; changing sandboxing has security consequences and official images already document the supported model.

If Jenkins publishes zero tests, verify the exact JUnit path, reporter configuration, current working directory, and whether Playwright started. allowEmptyResults prevents a secondary post-step failure but does not solve a missing report.

If tests pass locally and time out in CI, compare base URL, DNS, proxy settings, certificates, CPU, locale, and data. Open the trace before increasing timeouts. If all tests start failing together, suspect environment health or authentication rather than unrelated locator regressions.

If archived HTML opens without assets, archive the complete playwright-report/** tree. If the browser blocks archived HTML because of Jenkins content security settings, use an approved report publisher or download the artifact for local viewing according to company policy.

Interview Questions and Answers

Q: Why use both JUnit and the Playwright HTML reporter?

JUnit gives Jenkins structured test cases, build status integration, and history. The HTML report gives engineers steps, attachments, errors, and trace links. They solve different consumers' needs and can run together.

Q: Should Jenkins run npx playwright install --with-deps on every build?

It is acceptable on a disposable agent built for package installation, but it adds time and network dependency. A matching official Playwright container or prebuilt internal agent image is more predictable. Whichever approach you choose, package and browser versions must match.

Q: Where should retries be configured?

Configure the primary retry policy in playwright.config.ts so local reproduction and CI behavior are visible in source control. A common policy is zero locally and one in CI. Jenkins should not rerun a failed full build silently.

Q: How would you parallelize a large suite?

First make tests independent, then increase Playwright workers on one agent while measuring resource use. For a suite that still exceeds the feedback target, distribute deterministic shards across Jenkins executors and merge blob reports. Test data isolation is a prerequisite.

Q: How do you protect secrets in browser tests?

Store them in Jenkins credentials, bind them only around the test command, read them through environment variables, and disable shell tracing. Keep authentication state and secret-bearing traces out of public artifacts. Never place a secret in the Jenkinsfile or repository.

Q: What makes a Playwright pipeline reproducible?

A committed lockfile, pinned runtime or container, matching browsers, clean workspace, explicit configuration, and isolated test data. The same revision should produce the same dependency graph and test command on any compatible disposable agent.

Q: What would you inspect first for a CI-only timeout?

I would inspect the Playwright trace, the failing request, and the application's health for the same build. Then I would compare agent resources, network, base URL, locale, and test data with the local environment. Raising the timeout comes after identifying what is slow.

Common Mistakes

• Running npm install instead of npm ci, which can change dependency resolution during CI.
• Using a Playwright Docker image that does not match the package version in the lockfile.
• Publishing reports only on success, which discards the most valuable failure evidence.
• Enabling high worker counts before isolating accounts, records, queues, and rate limits.
• Rerunning the full job until it passes, which converts reliability defects into hidden debt.
• Echoing credentials or archiving storage-state files that contain authenticated cookies.
• Using fixed sleeps for application startup instead of webServer or a health check.
• Allowing Jenkinsfile changes from untrusted branches to access protected credentials.
• Keeping unlimited videos and traces until Jenkins storage becomes an operational incident.

Conclusion

A reliable Jenkins pipeline for Playwright is a versioned test environment, not merely a command that launches a browser. Commit the lockfile and configuration, use a compatible browser runtime, publish JUnit plus Playwright diagnostics on every outcome, and scale only after tests and data are independent.

Begin with the single-agent Jenkinsfile, deliberately break one smoke test, and verify the complete evidence path. Once that loop is trustworthy, add credentials, branch-based suites, and measured sharding without sacrificing reproducibility.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• GitHub Actions for Playwright: Step by Step (2026)
• Jenkins pipeline for Selenium: Step by Step (2026)
• Docker for Playwright: Step by Step (2026)
• CircleCI for test automation: Step by Step (2026)
• Docker for Selenium Grid: Step by Step (2026)
• Gatling basics for testers: Step by Step (2026)