Set Timezone & Locale for Playwright Screenshots
This guide explains how to control the timezone and locale when taking screenshots with Playwright. By setting these options, you can ensure that dates, times, numbers, and language-specific text appear consistently across your test environments, which is essential for visual regression testing and capturing accurate UI states.
What You’ll Need
- A Node.js project with Playwright installed (
npm init playwright@latest). - Basic familiarity with writing Playwright test scripts.
- Knowledge of your target timezone (e.g.,
America/New_York) and locale (e.g.,en-US).
Step-by-Step
- Open your Playwright test file. This is typically a
.spec.jsor.test.jsfile where you define your test cases. - Locate the test that takes the screenshot. If you have multiple tests, decide whether you want the timezone/locale applied to all tests (via a fixture) or just one.
- Add the timezone and locale to the browser context. In Playwright, these are set when you create a new context. If you are using the default test runner, you can pass them in the test’s options:
-
test('screenshot with custom timezone', async ({ page }) => { // The context is created automatically by the test runner. // To set timezone/locale, use test.use() at the top of the file. }); - Use
test.use()to apply settings globally. At the top of your test file, add: -
test.use({ locale: 'en-US', timezoneId: 'America/New_York', }); - For a single test, pass options directly. You can also set these inside the test using
test.use()within the test’s scope, or create a new context manually: -
test('screenshot with custom timezone', async () => { const browser = await chromium.launch(); const context = await browser.newContext({ locale: 'de-DE', timezoneId: 'Europe/Berlin', }); const page = await context.newPage(); // ... navigate and screenshot await page.screenshot({ path: 'screenshot.png' }); await browser.close(); }); - Verify the settings work. After navigating to a page that displays a date or time (like a clock widget), take a screenshot and check that the format matches the locale and the time is in the correct timezone.
- Run your test. Execute the test with
npx playwright test. The screenshot will be saved to the specified path.
Common Mistakes
- Using
timezoneinstead oftimezoneId. The correct property name istimezoneId, nottimezone. - Setting locale on the browser, not the context. Locale and timezone are context-level options, not browser-level. You must pass them to
newContext()ortest.use(). - Forgetting to apply
test.use()before the test. If you placetest.use()inside a test, it only affects that test, not subsequent ones. Place it at the top of the file for global effect. - Using invalid timezone IDs. Playwright uses the IANA timezone database. A typo like
America/NewYork(missing underscore) will cause an error. - Assuming locale changes the timezone. Locale only affects formatting (language, date format, number separators). It does not change the actual time. You must set both separately.
Tips
- Use a fixture for consistent settings. If you need the same timezone/locale across many tests, create a custom fixture that extends the default test object.
- Test multiple locales. For international apps, run the same screenshot test with different locales by parameterizing your tests.
- Combine with
page.emulateMedia(). You can also emulate color scheme and reduced motion alongside locale/timezone for a fully consistent screenshot. - Check the timezone offset. Use
page.evaluate(() => new Date().getTimezoneOffset())to verify the timezone is applied correctly. - Store screenshots with descriptive names. Include the locale/timezone in the filename, e.g.,
home-en-US-NY.png, to avoid overwriting.
Troubleshooting
- Error: “Invalid timezone ID” – Double-check the spelling. Use the exact IANA name, e.g.,
America/Los_Angeles,Asia/Tokyo. You can find a list at Wikipedia. - Locale does not seem to affect the screenshot. Some websites hardcode their language or use server-side detection. Try a page that uses the browser’s
navigator.languageorIntlAPI. Also, ensure you are not overriding the locale later in the test. - Timezone changes but date format does not. That’s expected – timezone affects the actual time, while locale affects formatting. If you need both, set both.
- Test runner ignores
test.use(). Make sure you are using the Playwright test runner (@playwright/test), not a custom runner. Thetest.use()method is only available in the test runner. - Screenshot shows a different time than expected. Check if the page uses a timezone that is not the browser’s. Some web apps fetch time from a server. In that case, you may need to mock the server response or use a feature like Playwright’s
page.clock(if available) to control time.
Frequently Asked Questions
Can I set timezone and locale for a single screenshot without affecting other tests?
Yes, create a new browser context within that test and pass the options to newContext(). That context will only be used for that screenshot.
What is the difference between locale and timezoneId?
locale controls language and formatting (e.g., date display, number separators). timezoneId sets the timezone, which affects the actual time shown (e.g., UTC+2 vs UTC-5).
Can I use a custom locale like ‘en-GB’ or ‘fr-CA’?
Yes, any valid BCP 47 language tag is accepted. Playwright uses the browser’s Intl API, so it supports all locales the browser supports.
Does setting the timezone affect the underlying system time?
No, it only changes the timezone reported to the page. The actual system time is not altered.
Will these settings work with Playwright’s visual regression testing?
Absolutely. That’s one of the main use cases. Consistent timezone/locale ensures that screenshots are comparable across runs.
What if I need to set a timezone that is not in the IANA database?
That is not possible. Playwright relies on the IANA database. If you need a custom offset, you may have to mock the Date object in the page, but that is more complex.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.