ScreenshotNeo
Sign in Get a free key

BlogGuides

Getting Started with Playwright for Java

Set up Playwright for Java, install its browsers, run a first script, and choose a path for tests and CI.

By the ScreenshotNeo team4 October 20269 min read

To get started with Playwright for Java, add the com.microsoft.playwright:playwright dependency to a Maven project, install Playwright’s browser binaries with its CLI, then run a small Java program that launches a browser and opens a page. Playwright supports Chromium, Firefox, and WebKit. The example below checks that the Java API and browser installation work before you add a test runner.

This guide follows the Maven path in the official Playwright Java introduction. The documentation showed version 1.63.0 during research for this article; check the live documentation for the current version before copying the dependency. Playwright’s introduction describes the library as created specifically for end-to-end testing.

1. Check the prerequisites

  • Install a JDK and Maven. The official introduction lists Java 8 or later.
  • Check the live requirements and supported operating systems for your machine or CI image. The documented list can change across Playwright releases.
  • Allow enough disk space and time for browser downloads. The browser binaries are separate from the Maven dependency.

The supported OS list in the documentation at research time included Windows 11 or later, Windows Server 2019 or later or WSL, macOS 14 or later, and Debian 12/13 or Ubuntu 22.04/24.04/26.04 on x86-64 or arm64. Treat that as version-sensitive information and verify the live requirements before choosing a CI image.

2. Create a Maven project

For a new project, create this minimal structure:

playwright-java-start/
├── pom.xml
└── src/
    └── main/
        └── java/
            └── App.java

Add the Playwright dependency to pom.xml. Use the current version shown in the official installation documentation in place of PLAYWRIGHT_VERSION.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId>
  <artifactId>playwright-java-start</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.source>8</maven.compiler.source>
    <maven.compiler.target>8</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.microsoft.playwright</groupId>
      <artifactId>playwright</artifactId>
      <version>PLAYWRIGHT_VERSION</version>
    </dependency>
  </dependencies>
</project>

If this is an existing project, add the dependency to its current build file rather than creating a second build configuration. Pin the dependency version so teammates and CI resolve the same Playwright release.

3. Install the browser binaries

From the project directory, use the Playwright CLI bundled with the Maven dependency:

mvn exec:java -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install"

This installs the browser binaries for the Playwright release in your project. To install just one browser, pass its name, for example:

mvn exec:java -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install webkit"

Playwright releases expect specific browser binaries. If you upgrade the Maven dependency, rerun the install command; an old browser installation may not match the new release. See the official Java browser documentation for OS dependency installation, browser caches, proxies, artifact repositories, and other installation options.

4. Run a first Java program

Create src/main/java/App.java:

import com.microsoft.playwright.Browser;
import com.microsoft.playwright.BrowserType;
import com.microsoft.playwright.Page;
import com.microsoft.playwright.Playwright;

public class App {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      Browser browser = playwright.chromium().launch();
      Page page = browser.newPage();
      page.navigate("https://playwright.dev");
      System.out.println(page.title());
      browser.close();
    }
  }
}

Run it with Maven’s compile and exec goals:

mvn compile exec:java -Dexec.mainClass=App

The program creates a Playwright instance, launches Chromium, navigates a page, prints its title, and closes the browser. The try-with-resources block closes the Playwright instance even if an exception occurs. Browser launches are headless by default, so a visible window is not required for this smoke test.

5. Capture a screenshot

Once navigation works, you can save a screenshot. This example uses WebKit; install it first with the named-browser command above.

import com.microsoft.playwright.Browser;
import com.microsoft.playwright.Page;
import com.microsoft.playwright.Playwright;
import com.microsoft.playwright.options.ScreenshotType;

public class ScreenshotExample {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      Browser browser = playwright.webkit().launch();
      Page page = browser.newPage();
      page.navigate("https://playwright.dev");
      page.screenshot(new Page.ScreenshotOptions()
          .setPath(java.nio.file.Paths.get("playwright-home.png"))
          .setType(ScreenshotType.PNG)
          .setFullPage(true));
      browser.close();
    }
  }
}

setFullPage(true) captures the full page rather than only the currently visible viewport. Keep a viewport screenshot when you specifically need what a user sees without scrolling. Playwright’s Java screenshot documentation describes screenshot options and their behavior.

6. Choose a browser and run mode

Choice When to use it
Chromium A practical starting browser for the first smoke test.
Firefox Include it when your coverage needs Firefox behavior.
WebKit Include it when your coverage needs WebKit behavior.
Headless (default) Use for normal automation and CI runs without a visible browser window.
Headed Use when you need to watch a run while debugging.

Choose the browser coverage your project needs, and install the matching binaries through the CLI. To see the browser UI, pass launch options:

Browser browser = playwright.chromium().launch(
    new com.microsoft.playwright.BrowserType.LaunchOptions()
        .setHeadless(false));

For slower visible execution while inspecting interactions, Playwright’s Java introduction also shows setSlowMo as a debugging aid. Keep these settings for diagnosis; headed mode is not required for local runs.

7. Move from a smoke test to an automated test

A standalone main method verifies that the dependency and browser can run. A maintained suite needs a test runner, assertions, and a lifecycle that creates and cleans up browser resources. Use the build tool and test runner already used by your Java project.

The official Playwright Java test-runner documentation covers conventional JUnit setup as well as Gradle configuration. The separate Playwright Java JUnit fixture integration uses @UsePlaywright and parameters such as Page; Playwright explicitly labels that integration experimental. Treat it as an option to evaluate, not a requirement for every Java test suite.

For an established suite, start with the official guides to Java test runners and writing tests and assertions. A web-first assertion waits for the expected page state instead of relying on an arbitrary fixed delay.

8. Set up Playwright in CI

CI needs the Java dependencies, matching Playwright browser binaries, and the operating-system libraries required to launch those browsers. A repeatable Maven job follows this order:

  1. Set up the Java and Maven environment used by the project.
  2. Resolve the pinned Playwright dependency.
  3. Install the required browser binaries and OS dependencies with the Playwright CLI.
  4. Run the Maven test command.

For Linux CI, the browser guide supports combining browser and OS dependency installation with the CLI’s install --with-deps option, for example:

mvn exec:java -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install --with-deps chromium"
mvn test

Install the default browser set instead if the suite needs more than Chromium. When using a Playwright container, align its tag with the Playwright package and browser binaries so the versions are not mixed casually. A container can provide a more consistent Linux browser environment. See the official Java CI documentation for current GitHub Actions and container examples; action versions change and should be checked when configuring a workflow.

9. Browser installation options for teams

The default CLI install is the right first step for most projects. In managed environments, the official browser guide also documents options for:

  • Installing operating-system dependencies separately or alongside browsers.
  • Using a proxy or internal artifact repository for downloads.
  • Sharing a browser cache between runs or configuring where browsers are stored.
  • Skipping downloads when the team manages browser binaries separately.
  • Listing installed browsers and removing browser installations.

These options depend on how your machines and CI are managed. Browser downloads can be substantial, so plan for first-run download time and disk use. The guide’s example download sizes are not stable guarantees.

Or skip the browser setup

If the task is to capture a website image or PDF rather than automate browser interactions, ScreenshotNeo is a website screenshot API and MCP server for developers. It can return a PNG, JPEG, WebP, or PDF from one GET request. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

cURL:

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

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://playwright.dev"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://playwright.dev'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await require('node:fs/promises').writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

See the ScreenshotNeo API documentation for request options. Sign up for 1,000 free screenshots a month with no card.

Troubleshooting

Symptom Likely cause Fix
Browser executable is missing The Playwright dependency is present but its browser binaries are not installed, or the dependency was upgraded. Run the CLI install command again using the project’s current dependency version.
Browser fails to launch on Linux CI Required OS libraries are missing. Install browser dependencies with the CLI’s install --with-deps option, or use a compatible documented container setup.
Maven cannot resolve the dependency The version placeholder was not replaced, the version is invalid, or repository access is unavailable. Use the current version from the official docs and confirm Maven can reach the configured repository or internal mirror.
The browser window does not appear Headless mode is the default. Set setHeadless(false) when you need a visible window and have a display environment available.
Navigation or a test times out The target page is slow, unavailable, or waiting for a page condition that does not occur. Check the target URL and network access, then wait for the specific page state your test needs rather than adding a large fixed sleep.
Works locally but fails in CI Local and CI environments may differ in browser binaries, OS libraries, or package versions. Make CI install browsers from the same pinned Playwright release and keep container and package versions aligned.

Performance, reliability, and cost notes

  • First run: Maven resolves the Java dependency and the CLI downloads browser binaries. Expect network and disk use during setup.
  • Repeat runs: Reuse the installed browser cache in a managed CI environment when appropriate, and reinstall after Playwright upgrades so versions remain compatible.
  • Reliability: Keep browser installation in the documented setup sequence and make the package, browser binaries, and CI image versions agree. Avoid making correctness depend on an arbitrary delay.
  • Cost: Playwright is a library dependency and the cited setup path does not require a paid screenshot service. Infrastructure costs depend on the machines and CI usage you choose; the research sources provide no benchmark or price comparison.

FAQ

Can I use Playwright for Java without Maven?

Yes. The official test-runner documentation includes a Gradle configuration route. Use the build system already adopted by your project.

Do I need all three browsers?

No. Install the browsers your coverage requires. You can install a named browser such as WebKit through the CLI.

Is the Playwright JUnit integration stable?

The fixture integration documented with @UsePlaywright is marked experimental. The Java test-runner guide also describes conventional JUnit setup.

Can I run the browser with a visible window?

Yes. Set setHeadless(false) in launch options when your environment has a display. Headless mode remains the default.

Keep reading

7 min read

LinkedIn Open to Work Image

Learn what LinkedIn’s Open to Work photo frame means, who can see it, how to add or remove it, and how to choose the right privacy setting.