How to run Playwright screenshot tests in Jenkins for an Indian development team
Build a repeatable Jenkins visual regression workflow with Playwright, reviewed baselines, pinned browser versions, and India-specific locale and timezone settings.
To run Playwright screenshot tests in Jenkins, use Playwright Test’s toHaveScreenshot() assertion on a Linux Jenkins agent with a versioned Playwright Docker image. Install the project’s dependencies with npm ci, keep the browser image compatible with the project’s Playwright package, commit reviewed screenshot baselines, and start with one CI worker for stable comparisons.
For an Indian development team, configure the browser locale and timezone according to the application’s actual requirements. The team’s location alone does not determine which locale the product should use. If test date output also depends on the runner process timezone, configure that separately with TZ.
1. Add a screenshot assertion to a Playwright test
Use Playwright Test’s screenshot assertion to capture a page after it has reached the UI state you intend to compare. The assertion waits for two consecutive screenshots to match before comparing the capture with the expected image.
import { test, expect } from '@playwright/test';
test('home page visual baseline', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot('home-page.png');
});Replace the example URL and test with your application’s route and required setup. If the page needs authentication, seeded data, or a particular interaction before it is ready, establish that state in the test before taking the screenshot. A screenshot comparison is useful only when the input state is repeatable.
Generate and review the first baseline
When a reference screenshot is missing, Playwright can generate one. Run the test in the environment you intend to use for comparisons, inspect the generated image, and commit it only after confirming it represents the intended UI. Keep accepted snapshots in version control so code review can examine visual changes.
When a UI change is deliberate, use Playwright’s snapshot update mechanism to regenerate the affected reference, then review and commit the change. Do not update baselines simply to make an unexplained CI failure disappear.
2. Run the test in Jenkins with a pinned Playwright image
Playwright’s Jenkins starting point is a Docker agent using a versioned Playwright image, followed by dependency installation and the test command. Here is the minimal Declarative Pipeline form:
pipeline {
agent {
docker {
image 'mcr.microsoft.com/playwright:v1.63.0-noble'
}
}
stages {
stage('e2e-tests') {
steps {
sh 'npm ci'
sh 'npx playwright test'
}
}
}
}Confirm the image tag against the Playwright version in your project before using it. The version shown is an example from Playwright’s CI documentation; available releases and tags can change. Add your organization’s repository checkout and report or artifact handling as required by your Jenkins setup.
The container image supplies browser binaries and system dependencies. It does not install your project’s npm Playwright package, so the job still needs npm ci from the project lockfile. Keep the image release and package version compatible; mismatches can leave Playwright unable to find the expected browser executables.
Playwright’s official documentation describes this approach in its Jenkins CI guidance. For the full Docker image and CI details, see the Playwright CI documentation and Docker documentation.
3. Configure browser locale and timezone for India-facing behavior
Set locale and timezone in the browser context when they affect the page’s language, formatting, or behavior. Choose values based on the product’s requirements, rather than assuming every India-facing application should use the same locale.
import { test, expect } from '@playwright/test';
test.use({
locale: 'en-IN',
timezoneId: 'Asia/Kolkata',
});
test('regional page rendering', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot('regional-page.png');
});Use the locale and timezone your application is expected to support. If you set a browser timezone but the test runner’s own date or time output must also use that zone, configure the runner process with TZ in Jenkins as a separate setting. Browser context emulation and runner process timezone are distinct controls.
4. Keep screenshot comparisons repeatable
Visual output can vary with the operating system, browser version, browser settings, hardware, power source, and headless mode. Create baselines and run CI comparisons in a consistent environment. A Docker-based Linux agent can help keep the browser and system dependency versions aligned; a managed Jenkins agent may also work if the team can maintain the same environment reliably.
- Pin the Playwright Docker image to a version compatible with the project package.
- Install dependencies from the committed lockfile with
npm ci. - Keep the operating system, browser build, viewport, and relevant page state consistent.
- Start with one worker in CI. Playwright recommends this as the stability-first default.
- Increase parallelism or shard work across jobs only after checking the agents’ capacity and confirming comparisons remain repeatable.
- Review expected, actual, and diff images when a comparison fails.
- Use pixel tolerances only as an explicit policy for understood variation.
Choose screenshot comparison tolerances deliberately
Playwright provides options such as maxDiffPixels and related thresholds to allow a known amount of visual variation. Select a tolerance based on acceptable product behavior and document why it exists. A broad tolerance can conceal a real UI change, so investigate unexplained differences before adjusting it. See the Playwright screenshot comparison options for available controls.
5. Handle baseline updates as code review
- Run the screenshot test in the pinned environment and inspect the failure output.
- Compare the expected image with the actual capture and diff image.
- Decide whether the visual change is intended or caused by nondeterministic page state or a different environment.
- If the change is intended, update only the affected snapshots using Playwright’s snapshot update mechanism.
- Review the changed screenshots alongside the code change, then commit them.
Keep baseline creation and CI comparison on compatible environments. A baseline captured on a different operating system, browser build, viewport, or rendering mode can produce differences that do not represent a product regression.
6. Troubleshoot common Jenkins screenshot failures
| Symptom | Likely cause | What to do |
|---|---|---|
| Playwright cannot find a browser executable | The project package and Docker image versions are incompatible, or dependencies were not installed. | Check the project’s Playwright package version, use a compatible image tag, and run npm ci from the lockfile. |
| A screenshot differs on Jenkins but passes locally | The local and CI operating systems, browser builds, viewport, settings, hardware, or headless mode differ. | Compare and align the rendering environment; inspect the expected, actual, and diff images before updating a baseline. |
| The first run reports a missing snapshot | No reference image exists yet for that assertion. | Generate the baseline in the intended environment, review it, and commit it to version control. |
| A visual failure appears after a planned UI change | The committed reference still represents the previous UI. | Review the actual and diff images, then update the relevant snapshot only if the change is intentional. |
| Date or localized text differs | The browser context locale or timezone does not match the product scenario, or the runner process timezone differs. | Set the required browser locale and timezone in Playwright. Set TZ separately for runner-process behavior when needed. |
| Small unexplained pixel differences keep failing | The rendering environment or page state is not stable, or the comparison policy does not allow a known, acceptable variance. | First stabilize the environment and page state. If a known variance remains, choose and document a narrow threshold such as an intentional maxDiffPixels value. |
| Parallel jobs produce inconsistent results | The agents may not have equivalent capacity or environments, or the workload may be exposing unstable page state. | Return to one worker while diagnosing. Consider more workers or sharding after measuring the actual agents and confirming repeatability. |
7. Decide between a Docker agent and a managed Jenkins agent
The Docker route is a practical default when Jenkins agents can run Docker and pull the required image. A managed agent can also run the tests, but the team then needs a dependable way to maintain compatible browsers, system dependencies, and operating system versions.
Before choosing, check whether your agents can run Docker, whether network policies allow pulling the image, who owns browser and dependency updates, and how consistently the environment can match the baseline. The right setup depends on your Jenkins installation and security policies.
8. Use ScreenshotNeo when you need captured pages outside the regression suite
Playwright Test is the do-it-yourself choice for visual regression assertions inside a Jenkins test suite. For a separate screenshot API workflow, ScreenshotNeo is a website screenshot API and MCP server. It accepts a URL in one GET request and returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for request options.
Or skip the browser setup:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie banners, popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.
FAQ
Does an Indian development team need to use an India-specific locale in every screenshot test?
No. Set the browser locale to match the application scenario being tested. Team location alone does not determine the product’s locale.
Does changing Playwright’s browser timezone also change Jenkins process time?
No. Configure the browser context timezone for page behavior and use TZ separately when the test runner process needs a specific timezone.
Should CI update screenshot baselines automatically?
Generate and review new references deliberately. Commit intended visual changes as part of code review rather than accepting unexplained CI differences.
Can a team add more than one Playwright worker in Jenkins?
Yes, if its agents have enough capacity and the results remain repeatable. Begin with one worker, then measure before increasing parallelism or sharding.
