ScreenshotNeo

BlogHow-to

How to Set the Playwright Timezone in Docker

Set the browser and test-runner timezones correctly in Playwright Docker environments, with TypeScript, Python, Dockerfile, troubleshooting, and CI guidance.

By the ScreenshotNeo team30 September 20267 min read

How to Set the Playwright Timezone in Docker

To set the timezone that web pages observe in Playwright running inside Docker, pass an ICU timezone ID such as Europe/Paris through the browser context’s timezoneId option. In Playwright Test, configure use.timezoneId globally or call test.use() for one test group. Set the container’s TZ environment variable separately when the Node.js or Python test-runner process itself must use that timezone.

These are two different layers:

  • Browser timezone: affects JavaScript date APIs, Intl.DateTimeFormat, and page behavior. Configure it with timezoneId.
  • Runner timezone: affects code executed by your test process. Configure it with Docker’s TZ environment variable.

Playwright documents this distinction in its emulation guide and defines timezoneId in the browser context API.

1. Choose the timezone setting you actually need

Requirement Setting Scope
Make the page think it is in Paris timezoneId: 'Europe/Paris' Browser context and pages
Make every Playwright test use Berlin use: { timezoneId: 'Europe/Berlin' } All tests in a project
Override one test or describe block test.use({ timezoneId: 'America/New_York' }) Selected tests
Change dates calculated by the test process TZ=Europe/Paris Runner process in the container

The browser context option defaults to the system timezone. It accepts timezone identifiers supported by ICU, so use region names such as Europe/Paris, Europe/Berlin, or America/Los_Angeles rather than informal abbreviations such as CET or PST.

Playwright's browser timezone and the Docker runner timezone are separate layers.
Playwright's browser timezone and the Docker runner timezone are separate layers.

2. Configure Playwright Test globally

This is the usual approach when all tests in a project should render dates in one location.

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

export default defineConfig({
  testDir: './tests',
  use: {
    timezoneId: 'Europe/Paris',
    headless: true,
  },
});

Save this as playwright.config.ts. The setting is applied when Playwright creates each test’s browser context. It therefore covers all pages created through the test fixtures.

Verify the browser timezone

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

test('page sees Paris time', async ({ page }) => {
  await page.goto('https://example.com');

  const result = await page.evaluate(() => ({
    zone: Intl.DateTimeFormat().resolvedOptions().timeZone,
    offset: new Date().getTimezoneOffset(),
    local: new Date().toString(),
  }));

  console.log(result);
  expect(result.zone).toBe('Europe/Paris');
});

The exact offset changes with daylight-saving rules. Assert the zone identifier or a formatted date for a known instant instead of hard-coding an offset that is valid only in one season.

3. Set a timezone for one test or test group

Use test.use() when most tests use the default but a smaller group needs another location.

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

test.describe('New York checkout', () => {
  test.use({ timezoneId: 'America/New_York' });

  test('shows the local order date', async ({ page }) => {
    await page.goto('https://example.com/checkout');
    await expect(page.locator('[data-testid="order-date"]')).toBeVisible();
  });
});

The override applies to tests inside the describe block. You can also place test.use({ timezoneId: 'Asia/Tokyo' }) at the top of a file to scope it to that file.

4. Configure a context when using the Playwright library

If you launch browsers directly instead of using Playwright Test, pass the option to browser.newContext().

import { chromium } from 'playwright';

const browser = await chromium.launch({ headless: true });
const context = await browser.newContext({
  timezoneId: 'Europe/Berlin',
});

const page = await context.newPage();
await page.goto('https://example.com');
console.log(await page.evaluate(() => Intl.DateTimeFormat().resolvedOptions().timeZone));

await context.close();
await browser.close();

Timezone emulation belongs to the context, so create separate contexts when a single process must test several locations. Do not reuse one context and expect its timezone to change after pages have been created.

5. Set the Docker runner timezone with TZ

timezoneId changes the browser. It does not change the timezone of the process running your tests. Playwright’s documentation recommends the TZ environment variable for that process.

docker run --rm \
  -e TZ=Europe/Paris \
  -v "$PWD:/work" \
  -w /work \
  mcr.microsoft.com/playwright:v1.55.0-noble \
  npx playwright test

Use an image tag that matches the Playwright version in your project. The official Docker image contains browsers and system dependencies, but the Playwright package still needs to be installed by your project. Playwright warns that mismatched image and package versions can prevent it from locating browser executables; see the Docker guide.

Docker Compose example

services:
  tests:
    image: mcr.microsoft.com/playwright:v1.55.0-noble
    working_dir: /work
    environment:
      TZ: Europe/Paris
    volumes:
      - .:/work
    command: sh -c "npm ci && npx playwright test"

Keep TZ and timezoneId together when your assertions involve both runner code and page code. For example, a helper that calls new Date() in Node.js uses TZ, while a date rendered by page JavaScript uses timezoneId.

6. A complete Docker project

The following files provide a small TypeScript project that runs in a Playwright container.

Set the context timezone, then verify the page's resolved timezone in a test.
Set the context timezone, then verify the page's resolved timezone in a test.

package.json

{
  "scripts": { "test": "playwright test" },
  "devDependencies": { "@playwright/test": "1.55.0" }
}

playwright.config.ts

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

export default defineConfig({
  testDir: './tests',
  timeout: 30_000,
  use: {
    timezoneId: process.env.BROWSER_TIMEZONE || 'Europe/Paris',
  },
});

tests/timezone.spec.ts

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

test('uses the configured browser timezone', async ({ page }) => {
  await page.goto('https://example.com');
  const zone = await page.evaluate(() => Intl.DateTimeFormat().resolvedOptions().timeZone);
  expect(zone).toBe(process.env.BROWSER_TIMEZONE || 'Europe/Paris');
});

Dockerfile

FROM mcr.microsoft.com/playwright:v1.55.0-noble
WORKDIR /work
COPY package*.json ./
RUN npm ci
COPY . .
ENV TZ=Europe/Paris
CMD ["npx", "playwright", "test"]

Build and run it with:

docker build -t timezone-tests .
docker run --rm timezone-tests

When changing the Playwright dependency, update the image tag at the same time. Pinning both versions makes CI failures easier to diagnose than using a floating image tag.

7. Python version

Python users configure the same browser context option. The runner process still receives its timezone through TZ.

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    context = browser.new_context(timezone_id="Europe/Paris")
    page = context.new_page()
    page.goto("https://example.com")
    zone = page.evaluate("Intl.DateTimeFormat().resolvedOptions().timeZone")
    print(zone)
    context.close()
    browser.close()
docker run --rm -e TZ=Europe/Paris your-playwright-image pytest

8. Timezone edge cases

Daylight saving time

Region identifiers include historical and daylight-saving rules. A location can have different offsets during the year. Test a fixed UTC instant and format it in the target zone when checking transitions.

UTC versus a region

Use UTC when you need a stable zero offset. Use a region such as Europe/Paris when the application must exercise local calendar and daylight-saving behavior.

Invalid identifiers

An unsupported ICU identifier can make context creation fail. Check the spelling and capitalization, and prefer IANA region names. Validate configuration at startup so a CI job fails before a long test run.

Dates generated outside the page

Data created in Node.js, Python, a database, or an API may already be UTC or may use the runner’s timezone. Browser emulation cannot rewrite those values. Make the source timezone explicit, then format in the page or application layer.

9. Troubleshooting checklist

Symptom Likely cause Fix
resolvedOptions().timeZone is unchanged TZ was set, but no timezoneId was supplied Add timezoneId to use or newContext.
Node.js dates are wrong while page dates are right The runner process uses another timezone Set TZ in Docker or the CI job.
Browser executable cannot be found Docker image and package versions differ Use matching Playwright versions and install the package in the project.
Context creation rejects the timezone Invalid or unsupported ICU identifier Use an IANA region ID such as Europe/Berlin or America/New_York.
Only some tests use the desired zone An override is scoped to a file or describe block Move the setting to global use configuration or adjust the scope.
Offset assertion fails in winter or summer Daylight-saving transition Assert the zone or format a known instant rather than a permanent offset.

10. Performance and reliability considerations

Timezone emulation is a browser-context setting; it does not require a separate browser process for every timezone. Reuse a browser while creating independent contexts for parallel locations. Close contexts after each test group so cookies, storage, and timezone assumptions cannot leak.

For reliable CI:

  • Pin the Playwright package and Docker image to compatible versions.
  • Log the configured TZ and browser timezone at the start of a job.
  • Use deterministic UTC timestamps in fixtures.
  • Include tests around daylight-saving transition dates if the product schedules local events.
  • Keep timezone selection in an environment variable so the same suite can run for several regions.

Timezone configuration itself has no separate Playwright charge. Your infrastructure cost comes from container runtime, browser startup, test duration, and parallel workers.

Or skip the browser setup

If your goal is a clean screenshot of a page in a particular timezone, ScreenshotNeo can handle the capture request without maintaining a Playwright container. Its API supports timezone configuration along with viewport, device, cookies, headers, JavaScript, waiting, blocking, and other capture options. Read the full parameter reference in the ScreenshotNeo documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import 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}`);

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result. An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and start with the 1,000 monthly shots.

FAQ

Does TZ replace timezoneId?

No. TZ configures the test-runner process. timezoneId configures the browser context seen by pages.

Can one test run cover several timezones?

Yes. Launch one browser and create a separate context with a different timezoneId for each location.

Should I use an offset such as UTC+1?

Use an ICU or IANA region identifier. Region IDs preserve daylight-saving rules; a fixed offset does not.

Why does my database date still show UTC?

Playwright only emulates the browser environment. Data produced by your API, database, or test runner must be converted explicitly before the page displays it.