Visual Testing for Electron Apps: Web in a Desktop Shell, Bugs Included

Key Points

Electron renders web content inside a desktop shell, which means your application inherits all web visual bugs — plus desktop-specific ones
Variable window dimensions, native menus, multi-monitor support, and cross-OS rendering differences create categories of visual bugs absent from the regular web
Testing an Electron app like a simple website is a mistake: the desktop context fundamentally changes the visual experience
Automated visual testing is the only viable approach to cover the OS x resolution x DPI x window size combinatorial space

Electron is defined by its official documentation as "a framework for building native desktop applications with web technologies (HTML, CSS, JavaScript), combining Chromium for rendering and Node.js for system-level access, in a single cross-platform runtime" (Electron Documentation, electronjs.org).

Behind this elegant definition lies a reality every Electron developer knows: you get the best of the web (ecosystem, productivity, rich UI components) and the worst of the web (CSS inconsistencies, rendering issues, variable performance). All of it topped with an extra layer of complexity from the desktop environment.

If you're developing an Electron application — and chances are you use several (VS Code, Slack, Discord, Figma, Notion, Obsidian) — this article will show you why visual testing of your desktop application deserves specific attention, and why treating it "like the web" isn't sufficient but remains the right starting point.

Electron Inherits All of the Web's Visual Problems

CSS Is Still CSS

Your Electron application uses the same rendering engine as Chrome (Chromium, via the Electron project which bundles a specific Chromium version). This means every web visual problem applies: CSS regressions after a dependency update, text overflows, z-index issues, improperly sized images, janky animations, fonts that fail to load.

If you've already done visual testing for the web, you know these problems. And they are exactly as present in Electron.

But here's the trap: many teams building Electron apps don't come from the web. They come from native desktop development (C++, C#, Java Swing) where CSS rendering issues don't exist. They encounter these problems for the first time, without the experience or tools to handle them.

Chromium Updates: The Silent Risk

Each major Electron update bundles a new Chromium version. And each new Chromium version can subtly change rendering. A modification to sub-pixel antialiasing, a change in rounding calculations, an evolution in font handling — these changes are rarely documented as breaking changes, but they can cause measurable visual regressions.

The Electron team publishes a new major version roughly every eight weeks. According to the official Electron blog, each major release integrates a Chromium version, a Node.js version, and a V8 version. That's a lot of potential change surface.

If you don't run visual tests before and after each Electron update, you're accepting a silent risk of regression across your entire interface.

Desktop-Specific Issues That Change Everything

Resizable Windows: Responsive on Steroids

On the web, "responsive design" means adapting the layout to a few predefined breakpoints (mobile, tablet, desktop). The possible viewports are numerous but bounded by existing screen sizes.

On desktop, your Electron application's window can take literally any size, from 400x300 pixels to 3840x2160, passing through every intermediate dimension. Users can resize freely, and they do.

This creates a continuous spectrum of possible layouts, not a discrete set of breakpoints. Your application must be visually correct at any size — and the intermediate sizes (those between your breakpoints) are often where problems appear.

Typical resizing bug scenarios include:

A sidebar that overlaps the main content when the window is too narrow to display both but too wide to trigger the "collapsed" mode.

A table that overflows its container and creates unexpected horizontal scrolling at certain widths.

Action buttons in a header that overlap when horizontal space is insufficient but the mobile breakpoint hasn't been reached yet.

A floating panel (inspector, terminal, command palette) that goes off-screen when the window is too small.

Native Menus: The Interface You Don't Control

Electron applications can use the OS's native menus (menu bar on macOS, window menu on Windows and Linux). These menus are rendered by the operating system, not by your CSS code. Their appearance varies according to the OS, the OS version, and the user's system theme.

Visually, the transition zone between the native menu and your web content is a frequent source of issues. On macOS, the title bar and menu are managed by the system. On Windows, many Electron apps use a custom title bar (frameless window with CSS-recreated control buttons) for a more modern look.

This custom title bar is a visually critical component. The close, minimize, and maximize buttons must be in the right place, the right size, the right color, and behave correctly on hover. And all of this varies across platforms: on macOS, the buttons are on the left and round; on Windows, they're on the right and square; on Linux, it depends on the window manager.

If your application uses a custom title bar, visual testing must cover it on each target OS. It's a component users see and use constantly, and a visual bug here is immediately noticeable.

Multi-Monitor and Variable DPI

The modern desktop environment often means a laptop with a Retina display (2x DPI) connected to an external 1080p monitor (1x DPI). Users move your application from one screen to another. And when the application moves from a 2x to a 1x screen, everything must re-render correctly.

DPI-related visual problems are particularly insidious:

Bitmap images (PNG, JPG) designed for a single DPI appear blurry on high-resolution screens or pixelated on low-resolution ones. Icons and illustrations must be provided in multiple resolutions or in vector format (SVG).

1-pixel borders don't display the same way in 1x and 2x. On a 2x screen, a 1-pixel CSS border is 0.5 physical pixels, which can make it invisible or inconsistent depending on the rendering engine.

Drop shadows, gradients, and blur effects subtly change rendering between resolutions. What is a slight blur on a 1x screen becomes a pronounced blur on a 2x screen, or vice versa.

Text undergoes different antialiasing. The readability of a thin font can be excellent at 2x and poor at 1x. The typographic choice that works on your development screen (probably a MacBook Retina) can be disastrous on your user's external monitor.

The Taskbar, Dock, and System Tray

Your application interacts with the desktop environment through the taskbar icon (Windows/Linux), the dock (macOS), and the system tray. These tiny icons (16x16 to 48x48 pixels) must be flawless. Notification badges, status overlays, context menus — these are visual elements your users see constantly, even when your application isn't in the foreground.

Three OSes: Three Renderings, Three Sets of Problems

macOS: The Demanding Reference

macOS is often the primary development platform. Visual specifics include the traffic light buttons (red, yellow, green) on the left, Core Text font rendering (visually "bolder" at the same weight compared to Windows), and native dark mode handling that must harmonize with your application's theme.

Windows: Configuration Diversity

Windows offers the greatest configuration diversity. Resolutions range from 1366x768 (still 20% of screens according to StatCounter in 2025) to 3840x2160. Scaling factors (100% to 200%) add a complexity absent on macOS.

DirectWrite font rendering produces noticeably different results from Core Text: thinner, sharper fonts, sometimes less readable at small sizes. The "High Contrast" accessibility mode can drastically change your application's appearance if your CSS styles don't support it.

Linux: The Special Case

The fragmentation of desktop environments (GNOME, KDE, XFCE) makes normalization difficult. But according to the Stack Overflow Developer Survey 2024, about 27% of developers use Linux. If your application targets developers, Linux deserves coverage. The minimum viable: Ubuntu with GNOME.

Visual Testing Strategy for Electron

Define Your Test Matrix

The first step is to explicitly define the combinations you'll test. At a minimum, your matrix should include:

Target OSes. macOS (latest and previous versions), Windows 10, Windows 11. Linux Ubuntu LTS if your audience justifies it.

Priority screen resolutions. For each OS, the two or three most-used resolutions by your users. On macOS: 1440x900 and 2560x1600 (Retina). On Windows: 1920x1080 and 1366x768. Adapt based on your actual analytics data.

DPI factors. 1x and 2x at minimum. On Windows, add 1.5x (150%) which is a very common setting.

Window sizes. Full screen, half-screen (split screen), and a reduced "minimum functional" size. These three sizes cover real-world usage scenarios.

Automating Capture Across Multiple OSes

The main technical challenge of Electron visual testing is capturing screenshots across multiple OSes. You have several options.

The multi-platform CI approach. GitHub Actions, GitLab CI, and Azure Pipelines support jobs on macOS, Windows, and Linux. Configure a visual testing job per OS that launches your application, navigates to the screens to test, and captures screenshots.

The Playwright approach. Playwright natively supports Electron automation since version 1.20: launching the app, interactions, screenshot capture, all cross-platform.

The Delta-QA approach. For teams that don't want to maintain scripts, Delta-QA offers a no-code approach to capture and visually compare your application's screens.

Priority Zones to Monitor

In an Electron application, certain areas are more prone to visual regressions than others. Focus your visual tests on these zones:

The title bar and window controls. If you use a custom title bar (frameless window), test it on each OS. The close/minimize/maximize buttons, the drag area, the application title — everything must be pixel-perfect and conform to platform conventions.

Resizable panels. If your application has panels (sidebar, bottom panel, inspector) that users can resize, test the rendering at different panel sizes. Resize handles, minimum and maximum sizes, content that adapts — all of this must be visually correct.

Context menus. Native context menus render differently on each OS. Custom context menus (in CSS) must be tested for positioning (not overflowing the window), readability, and consistency with the application's theme.

Modals and dialogs. System dialog boxes (open file, save, print) are native and don't require visual testing from your side. But your application's custom modals must be tested, particularly their centering, overlay, and behavior when the window is small.

Loading states and transitions. Starting an Electron application can take a few seconds. What the user sees during this time (splash screen, loading screen, empty window) is part of the experience and deserves visual testing.

The Most Common Mistakes

Testing Only on One OS

This is the most common and most costly mistake. If your team develops on macOS and tests on macOS, visual bugs specific to Windows and Linux reach production unfiltered. And Windows typically represents the majority of your Electron user base (according to data from Electron Fiddle and many popular Electron applications, Windows often accounts for 60 to 70% of installations).

Ignoring DPI Factors

Testing only at 1x when a significant proportion of your users are at 2x (or vice versa) is a recipe for surprises. DPI issues are subtle — slightly blurry text, vanished borders, pixelated icons — but they give an impression of lack of polish that erodes trust.

Treating Electron Like a Web Browser

Your Electron application is not a browser tab. It's a desktop application that the user has installed, that has its own space in the taskbar, and that is judged by native application standards. Users tolerate a website with a slightly broken layout. They don't tolerate an installed desktop application with obvious visual issues.

Neglecting Intermediate Window Sizes

If you only test in full screen, you miss all bugs that appear when the user runs your application in half-screen (split screen with another application). This is an extremely common usage on desktop, especially for productivity tools.

FAQ

Electron uses Chromium, so regular web tests are enough, right?

No. Electron uses Chromium for rendering, that's true. But the environment is fundamentally different: infinitely resizable windows, no address bar, native OS menus, taskbar integration, multi-monitor support, variable DPI. Your regular web tests cover Chromium rendering in a browser. They don't cover Electron desktop environment specifics. Both levels are necessary.

How do you handle font rendering differences between macOS and Windows?

Font rendering differs structurally between Core Text (macOS) and DirectWrite (Windows). The only reliable way to handle these differences is to maintain separate visual baselines per OS. Don't compare a macOS screenshot with a Windows screenshot — they will always be different, and these differences are normal. Compare macOS with macOS, Windows with Windows.

Should you test every Electron version update?

Yes, and it's non-negotiable. Every major Electron update bundles a new Chromium version that can change rendering. The best practice is to run your complete visual test suite before and after the update, compare the results, and validate the differences. Some differences will be rendering engine improvements (which you can accept by updating baselines), others will be regressions (which you must fix or report).

How do you test Windows High Contrast mode?

Windows High Contrast Mode is an accessibility setting that replaces your application's colors with a high-contrast color scheme. You can enable it programmatically in your CI test environment (via system settings or automation tools). Capture screenshots in this mode and maintain a dedicated baseline. This is particularly important if your application targets professional environments where accessibility policies are strict.

My Electron app only targets macOS. Is multi-OS testing still necessary?

If your application truly only supports a single OS, multi-OS testing is obviously not necessary. But verify this assumption: many "macOS only" applications discover that some of their users run the application on Windows via unofficial installations or enterprise requests. If you're considering future Windows support, investing in multi-OS testing now will considerably ease the transition.

What is the ideal visual testing frequency for an Electron application?

At every commit that touches the interface, and at every Electron version or UI dependency update. In practice, integrate visual testing into your CI/CD pipeline so it runs automatically on every pull request. The cost of an occasional false positive is infinitely lower than the cost of a visual regression shipped to thousands of desktop users.