Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
There are two different ways to “highlight” an element with Playwright. To mark it temporarily in the live browser while debugging, call locator.highlight(). To save an image that shows an outline around an element, apply screenshot-time CSS and capture the page. By contrast, locator.screenshot() saves a crop of the element itself; it does not create a full-page screenshot with that element marked.
Choose the kind of highlight you need
| Your goal | Use | What you get |
|---|---|---|
| See which element a locator matches while debugging | locator.highlight() |
A temporary visual overlay in the browser, not an annotated image file. |
| Save just the target element | locator.screenshot() |
An image cropped to the element’s bounds. |
| Save a viewport or full page with the target outlined | page.screenshot() with its style option |
A page image rendered with temporary CSS styling. |
| Find or inspect a locator interactively | Playwright UI Mode or Inspector | A debugging workflow for inspecting candidates and refining a locator. |
The distinction matters: a browser overlay helps you verify a locator, while screenshot-time styling changes what appears in the saved image. Playwright describes highlight() as a debugging aid and cautions against committing code that uses it. See the Locator API and Screenshots guide.
Show a live debugging highlight
First choose a locator that identifies the intended element clearly. For a button, a role and accessible name are often more robust and readable than a broad CSS selector:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsconst button = page.getByRole('button', { name: 'Save' });
await button.highlight();This asks Playwright to highlight the element matched by the locator in the live page. It does not save a screenshot or alter the element’s application styling permanently. The API also supports a custom CSS style:
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
await locator.highlight({ style: 'outline: 2px dashed red' });Use a locator variable that you have already defined, or replace locator with your own locator expression. The documented hideHighlight() method hides a highlight previously added with highlight(). These calls are best used temporarily while investigating a test; keep them out of committed test logic.
Save an image of the element alone
Use a locator screenshot when the desired artifact is a close-up of the matched element:
await page.getByRole('button', { name: 'Save' }).screenshot({ path: 'save-button.png' });The output is clipped to the target’s position and size. It is not a full-page image with a box drawn around the target. Playwright scrolls the element into view and performs actionability checks before capturing it; the call can fail if the element is detached from the DOM.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
Visibility constraints
- If another element covers the target, the covered portion will not become visible just because it was captured.
- For an element in a scrollable container, the screenshot includes the container’s currently scrolled content, not content hidden outside that view.
- If you need surrounding context or a page-wide annotation, use a page screenshot rather than an element screenshot.
These behaviors and screenshot options are documented in the Locator API.
Save a page screenshot with the element outlined
For a marked image, apply a temporary stylesheet as part of the screenshot call. The selector below is illustrative: change it to match the target in your page. A data-testid is useful only if your application actually has that attribute.
await page.screenshot({
path: 'highlighted-page.png',
style: `
[data-testid="save-button"] {
outline: 3px solid red !important;
outline-offset: 3px !important;
}
`,
});This captures the page with CSS applied for the screenshot. The style option is documented for screenshots and its stylesheet pierces Shadow DOM and applies to inner frames. It was added in Playwright v1.41, so confirm the installed package’s matching API documentation if the option is unavailable. A page screenshot can capture the viewport or the full page:
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
await page.screenshot({ path: 'highlighted-page.png' });
await page.screenshot({ path: 'highlighted-full-page.png', fullPage: true });The first call captures the page viewport; setting fullPage: true requests a full-page capture. The Screenshots guide also shows how to return screenshot bytes in a buffer when you need to process the image in code instead of writing it directly to a path.
Make the annotation visible without changing the app
- Use an outline rather than a border when you do not want the highlight to change the element’s layout.
- Use
!importantwhen the page’s existing styles would otherwise override the temporary highlight. - Give the outline an offset if it would blend into the element’s edge.
- Check that the selector matches only the intended target. A broad selector can mark multiple elements.
Playwright also documents mask and maskColor screenshot options. Those cover matching elements with colored boxes; they are useful for masking content, not for drawing a transparent outline around a target. Consult the Locator API for the options available in your installed version.
Choose a locator that points to the right target
A highlight only helps if the locator selects the intended element. Playwright recommends user-facing locator methods such as getByRole(), getByText(), getByLabel(), and getByPlaceholder(); getByTestId() is another option when test IDs are appropriate for the project. The Locators guide explains these methods and how to refine a locator.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
For example, if the page contains several buttons named “Save,” narrow the locator to the relevant part of the page rather than assuming the broad role-and-name locator is unique. The guide demonstrates filtering a list item before taking its screenshot; the same idea applies to locating an element in its surrounding context. Prefer a selector whose meaning is clear to someone reading the test later.
When the target is not obvious
Playwright UI Mode and the Inspector can help you identify a candidate before writing a screenshot call. In UI Mode, inspect test runs and DOM snapshots; the locator picker highlights candidates while you hover. The Inspector lets you edit a locator and see live highlighting in the browser. These are interactive inspection tools, whereas locator.highlight() can be called directly from code. See UI Mode and Running and debugging tests.
Recommended Free Tools
Check your Playwright version and capture options
Playwright’s screenshot options are versioned. The Locator API documents the custom highlight() style option as added in v1.60 and the screenshot style option as added in v1.41. Check the API reference that matches the Playwright package installed in your project before relying on either option; the current online page may describe a newer version than your project uses.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
Screenshot calls offer other controls—including output path, image type, quality, scale, animation handling, caret behavior, masks, and timeout. Use only the controls that affect the artifact you need. For example, output path determines where a file is written, while the screenshot-time stylesheet is what adds the outline in the page-image method above. Refer to the Locator API for exact option names and supported values for your version.
Troubleshoot missing or incorrect highlights
The overlay does not appear
- Confirm that your locator matches the element you intend to inspect. Use a role, accessible name, or an appropriate test ID, then refine it if more than one element matches.
- Confirm that the code reaches the
highlight()call and that the page and locator are still available. - Check the installed Playwright version if you are using the custom
styleargument tohighlight(); the API documents that style option as added in v1.60.
The saved page image has no outline
- Check that the screenshot-time CSS selector matches the element in the page being captured. A sample test ID is not automatically present in your application.
- Check whether the page’s CSS overrides the annotation; an outline declaration with
!importantcan help. - Check the installed Playwright version for support for screenshot-time
style, documented as added in v1.41.
The element screenshot is clipped or incomplete
- Remember that
locator.screenshot()captures the element bounds, not the entire page. Switch topage.screenshot()if you need surrounding page context. - Check whether another element covers the target or whether it sits in a scrollable container. Covered portions remain obscured, and only the currently scrolled content is included.
- If the element is removed or replaced during capture, the locator screenshot can throw because the target detached from the DOM.
Or skip the browser setup
If your goal is a clean website capture rather than a Playwright debugging overlay or a red annotation, ScreenshotNeo can return a screenshot from one GET request. Its screenshot API does not replace the CSS annotation method above; use Playwright when the saved image must show a custom outline.
Example using cURL (replace the target URL with the page you want to capture):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for setup and available options. Cookie banners, popups and chat widgets are removed before the shot; bot checks, blank pages and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free.
Frequently Asked Questions
Can I use locator.highlight() in a committed test?
Playwright positions it as a debugging aid and cautions against committing code that uses it. Remove temporary highlighting once you have finished inspecting the locator.
Does locator.screenshot() put an outline around the element in a full-page image?
No. It saves an image clipped to the matched element. Use a page screenshot with screenshot-time CSS when you need the whole page or viewport with an outline.
What should I use if my Playwright version does not support the screenshot style option?
Check the API reference matching the installed package. The documented screenshot style option was added in v1.41; an alternative is to capture a screenshot buffer and annotate the image in a separate image-processing step.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
