How to Start Playwright with a Maximized Window

Direct answer: In Playwright Test, run Chromium headed and pass --start-maximized through the project’s launchOptions. For a one-off run, add --headed. A maximized outer window and the page viewport are separate settings.

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

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: {
        headless: false,
        launchOptions: {
          args: ['--start-maximized'],
        },
      },
    },
  ],
});

This follows the Playwright Test options example. Playwright warns that custom browser arguments can break functionality, so keep this argument scoped to Chromium and remove it if your environment becomes unstable.

What “maximized” means in Playwright

Window: the operating-system browser window. --start-maximized asks Chromium to open that window maximized.

Viewport: the width and height exposed to page content. Playwright’s default viewport is 1280×720. A fixed viewport gives repeatable layout and screenshot results; it does not maximize the outer window.

Setting viewport: null disables Playwright’s fixed viewport emulation and lets page dimensions follow the host window. The dimensions then vary with the desktop, window manager, display scaling and CI runner. Use it only when matching the visible host window is the goal.

Playwright Test configuration

Headed, maximized Chromium with host-sized content

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

export default defineConfig({
  use: {
    browserName: 'chromium',
    headless: false,
    viewport: null,
    launchOptions: {
      args: ['--start-maximized'],
    },
  },
});

Run with npx playwright test. The browser window is visible, starts maximized when the platform honors the flag, and the page follows the host window.

Keep deterministic page dimensions

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

export default defineConfig({
  use: {
    browserName: 'chromium',
    headless: false,
    viewport: { width: 1440, height: 900 },
    launchOptions: {
      args: ['--start-maximized'],
    },
  },
});

This is usually the better choice for visual tests. The window can be maximized for observation while assertions and screenshots use 1440×900.

One-off headed run

npx playwright test --headed

The CLI flag enables a visible browser but does not maximize it. Put the argument in configuration (or launch Chromium directly) when maximization is required.

Direct Playwright library use

import { chromium } from 'playwright';

const browser = await chromium.launch({
  headless: false,
  args: ['--start-maximized'],
});
const context = await browser.newContext({ viewport: null });
const page = await context.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
await page.screenshot({ path: 'example.png' });
await browser.close();

chromium.launch() creates the browser, newContext() sets emulation, and newPage() creates a tab. See the BrowserType API. The documented maximization example is Chromium-specific; do not assume identical behavior in Firefox or WebKit.

Choosing the right settings

Goal	Settings	Trade-off
See a browser while tests run	`headless: false` or `--headed`	Visible window; not automatically maximized.
Start Chromium maximized	`launchOptions.args: ['--start-maximized']`	Uses a Chromium switch; custom args carry compatibility risk.
Follow the host window	`viewport: null`	Dimensions vary by machine and display.
Repeatable screenshots	Fixed `viewport`	Predictable content area; outer window size is separate.

Validation checklist

Use the Chromium project or chromium.launch().
Set headed mode with headless: false or --headed.
Add --start-maximized under launchOptions.args.
Choose viewport: null only for host-sized content; otherwise set explicit dimensions.
Run on the same OS, display scale and window manager when comparing screenshots.

Troubleshooting

The window is not visible

Headless mode is the default. Set headless: false or run with npx playwright test --headed. In a container or remote CI session there may be no display; headed mode then needs a desktop session or virtual display.

The window opens but is not maximized

Confirm the argument is nested under the active project’s use.launchOptions, and that the project uses Chromium. Desktop policies, Linux window managers and remote runners can ignore startup hints. Treat the viewport as the reliable control for layout dimensions.

Content is still 1280×720

That is Playwright’s fixed default viewport. Set viewport: null to follow the host window, or specify the exact width and height you need.

Tests became flaky after adding arguments

Playwright documents that custom browser args are used at your own risk. Remove unrelated switches, keep only --start-maximized, and verify behavior with a clean browser launch.

Firefox or WebKit behaves differently

The cited maximization configuration is for Chromium. Use fixed viewport dimensions for cross-browser consistency and consult each browser’s supported launch options before adding flags.

Works locally but fails in CI

CI often has no window manager, a different display scale, or runs headless by policy. Prefer a fixed viewport for assertions; use headed mode only when the runner provides a display. Capture diagnostic values such as page.viewportSize() and the browser name.

Performance, reliability and cost

Maximizing a window does not make page loads faster and can add variability when the viewport follows the host. Fixed viewports reduce screenshot diffs and make parallel runs easier to compare. A visible browser consumes desktop resources; headless execution is generally simpler for CI. The Playwright setting itself has no separate fee; your costs come from the machines or CI minutes that run the browser.

Or skip the browser setup

If your goal is a clean image or PDF rather than controlling a local window, ScreenshotNeo captures a URL with one request. Cookie and consent banners, newsletter popups and chat widgets are removed before the shot; bot checks, blank pages, failed loads and cache hits are not billed. Responses identify the page verdict and billing with X-Page-Verdict and X-Billed headers. Its MCP server lets Claude, Cursor and other MCP clients call take_screenshot, get_page_info and capture_pdf.

See the ScreenshotNeo API docs for all options.

cURL

curl -G 'https://api.screenshotneo.com/v1/shot' -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

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)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const buffer = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', buffer);

Plans include 1,000 screenshots each month free with no card; paid plans start at $5 for 3,000 shots. Every feature is on every plan. Create a free ScreenshotNeo account.

FAQ

Does `--start-maximized` change the page viewport?

No. It requests a larger outer Chromium window. Set viewport separately.

Can I maximize in headless mode?

There is no visible OS window in headless mode. Set a viewport to control page dimensions instead.

Should visual regression tests use `viewport: null`?

Usually no. A fixed viewport keeps renders stable across developers and CI agents.

Is this switch portable across operating systems?

Playwright documents the Chromium example but does not promise identical window-manager behavior on every platform. Verify on the environments you support.