Automated Cross-Browser Layout Testing with Galen Framework

Galen Framework automates cross-browser layout testing by opening a page in a Selenium-controlled browser, setting a viewport, and checking the page against a layout specification you write. A spec can describe element positions, sizes, visibility, and relationships, so a test can catch a navigation bar overlapping content on a narrow screen even when the page still loads successfully.

The basic workflow is: install Galen and a compatible browser driver, describe the expected layout in a .gspec file, configure a browser or Selenium Grid, and run a Galen check. When a check fails, inspect the generated report and failure screenshot. Browser and driver support changes over time, so confirm compatibility against the versions in your environment.

Galen is a layout-testing framework, not merely a screenshot capture tool. It uses Selenium to select page elements and inspect their geometry. Its project materials also describe functional and image/color-related testing capabilities. See the official Galen documentation and framework overview.

1. What Galen checks and what it does not

A Galen test checks a layout contract that your team defines. That contract can state where an element should appear relative to another, how large it should be, and whether it should be visible under a viewport or device tag. Galen opens the page in a browser, resizes it, and evaluates those conditions.

This makes Galen useful for regressions that can be described as measurable relationships: a logo should sit inside the header, a menu should remain visible at desktop width, or a mobile control should replace a desktop navigation element. It does not infer your intended design. You must author expectations that reflect the design.

Galen reports failed checks and can provide screenshots with failing elements highlighted. Use those artifacts to understand whether the cause is a genuine layout change, different content, or an environment issue. Consult the official documentation for the supported spec syntax and checks.

2. Install Galen and prepare a browser

Install Galen using the current instructions on the Galen getting-started documentation. You will also need a browser and the matching WebDriver setup for the browser you plan to automate. Galen’s browser configuration guide documents local browser setup and driver paths, including ChromeDriver configuration: Configuring browsers.

Keep Galen, Selenium, the browser, and its driver versions compatible. The documentation includes browser examples that may reflect older releases; do not assume every listed browser or old version example is supported by your current environment. The First Project tutorial specifically advises checking Selenium compatibility if browser execution fails.

1. Install Galen according to the current official setup instructions.
2. Install a supported browser in the environment where the test will run.
3. Configure its WebDriver executable or the documented driver path.
4. Run a small browser-opening test before adding a large suite of layout assertions.
5. Record the Galen, Selenium, browser, and driver versions in your project or CI environment.

3. Write a layout specification

Create a Galen spec file, for example specs/homepage.gspec. Galen Specs describe the page objects and the spatial relationships you expect. The precise grammar and available checks are documented in the Galen reference; use that reference when adapting the illustrative spec below to your installed version.

@objects
    header          .site-header
    logo            .site-header .logo
    navigation      .site-nav
    mainContent     main
    mobileMenu      .mobile-menu-button

@on desktop
    header:
        inside screen
        height > 48px

    logo:
        inside header
        left of navigation
        vertically aligned with header

    navigation:
        visible
        inside header

    mainContent:
        below header

@on mobile
    header:
        inside screen

    mobileMenu:
        visible

    navigation:
        absent

This example is a starting point, not a guarantee that every selector or assertion syntax is valid across Galen releases. Check the current spec reference and make sure the selectors match your page. In particular, avoid brittle selectors tied to generated class names when stable IDs, semantic attributes, or dedicated test selectors are available.

Decide which constraints represent user-visible requirements. Use a small set of meaningful checks for each page and viewport class. A spec with too many incidental pixel assumptions can fail after harmless design adjustments; overly loose checks can miss real breakage.

4. Run a check locally from the command line

The Galen First Project tutorial demonstrates running a check with a URL and viewport size and says the run produces an HTML report. The command below follows that documented command-line pattern; confirm exact command options against the installed Galen version and tutorial before using it in automation.

galen check specs/homepage.gspec https://example.com 1366x768

Replace https://example.com with the page under test and adjust the viewport to a size your design supports. Run the command after the WebDriver and browser are configured. Review the HTML report and any failure screenshots, then fix either the implementation or the spec if the observed result is intentional.

For a basic test sequence, start with one page and one viewport. Add a mobile viewport and a second browser once the local run is stable. The First Project tutorial covers the initial project flow and report.

5. Organize viewports, tags, and a test suite

Use viewport sizes to represent the layout classes that matter to your users, rather than attempting every possible pixel width. Tags let a spec apply different expectations to desktop, tablet, or mobile layouts. Keep the mapping between viewport and tag explicit so that the test suite communicates which contract is being checked.

Galen’s test suite syntax supports test entries with browser and page configuration, including local and Grid execution. Review the test suite syntax reference for the current structure. A practical suite should identify the page, browser configuration, viewport, and spec for each case.

1. List the pages whose layout failures would block a release.
2. Choose representative viewport classes based on your product’s breakpoints and high-risk layouts.
3. Write assertions for visibility, size, and relationships that matter at each class.
4. Run the same important page and viewport combinations in the browser families your users need.
5. Keep a fast core suite for pull requests and run broader combinations where CI capacity allows.

The last two steps are operational recommendations based on the kinds of local and Grid configurations Galen documents, not a prescribed Galen setup. Tune the matrix to the browsers and devices your product supports.

6. Run Galen with Selenium Grid or hosted browsers

A local browser is a straightforward starting point. Selenium Grid is useful when tests need remote browser sessions, multiple browser configurations, or parallel execution. Galen’s configuration guide describes Grid settings, including a Grid URL and browser parameters, while the suite reference describes Grid test entries. See Configuration and Test Suite Syntax.

Galen’s site names HeadSpin, LambdaTest, Sauce Labs, and BrowserStack as cloud options for running Galen tests against different mobile devices. That is a list of options named by Galen, not a verified current compatibility matrix or endorsement. Check each service’s current browser availability, capabilities, pricing, and terms before choosing one: Galen product site.

Choose an execution route by considering the browsers and device coverage you need, control over viewport dimensions, local setup and maintenance, and whether parallel runs matter. These are decision factors inferred from Galen’s documented local, Grid, and hosted configurations; the sources do not provide a current vendor-by-vendor comparison.

7. JavaScript integration

Galen supports JavaScript and Java integrations in addition to its own specs and suite syntax. The JavaScript API includes operations for creating a driver, resizing the browser, and checking a layout. Its API is version-sensitive, so consult the official JavaScript API reference and use the package and syntax documented for the version installed in your project.

Conceptually, a JavaScript test follows this sequence:

1. Create or connect to a Selenium WebDriver session.
2. Open the target URL.
3. Set the required viewport dimensions.
4. Run a layout check against the relevant spec and tag.
5. Close the driver session even if an assertion fails.

The dossier does not provide a version-pinned JavaScript package manifest or complete executable integration snippet, so avoid copying guessed imports into a production project. Use the official API page to select the exact setup for your Galen version.

8. Troubleshooting common failures

Symptom	Likely cause	What to check or fix
Browser will not start	Missing driver, wrong driver path, or browser/driver mismatch	Confirm the browser is installed, configure the driver path using the browser setup guide, and check version compatibility.
Session creation fails on Grid	Incorrect Grid URL or browser capability parameters	Check the Grid endpoint and browser parameters in project configuration and the configuration guide.
Element is not found	Selector does not match, element is rendered later, or page differs in that browser	Inspect the page in the same browser and viewport; use stable selectors and ensure the page has reached the state your test expects.
Layout check fails only at one size	A breakpoint changes visibility, positioning, or dimensions	Inspect the failure screenshot and report; verify the correct viewport and tag are paired with the spec’s expectations.
Check passes locally but fails remotely	Browser versions, fonts, timing, network, or viewport differ	Compare environment versions and viewport settings, then make page readiness and test data consistent.
Unexpectedly many pixel-level failures	Spec asserts incidental dimensions or content shifts between runs	Keep assertions tied to intended layout constraints; stabilize dynamic content where possible and adjust tolerances using supported Galen syntax.
No useful report or failure screenshot	Run command or output handling differs from the installed version	Follow the current First Project tutorial and inspect the command’s output directory and CI artifact collection.

When diagnosing a failure, first reproduce it with the same browser, viewport, URL, and test data. Then decide whether the page or the declared contract changed. Do not weaken a spec until you have inspected the evidence.

9. Performance, reliability, and cost

Galen’s runtime depends on the pages, browsers, assertions, and execution environment; the research sources provide no benchmark figures. More browser and viewport combinations mean more sessions to provision and maintain. Parallel Grid execution can reduce wall-clock time when capacity is available, while also increasing infrastructure use and the number of concurrent browser sessions.

For reliability, pin or record tool and browser versions where practical, keep test data deterministic, and collect reports and failure screenshots as CI artifacts. Browser and driver compatibility is version-sensitive, so schedule updates deliberately and revalidate the core suite when changing versions. For hosted services, verify current cost and availability directly with the provider; no vendor prices or terms were established by the research for this article.

10. Or skip the browser setup

If your immediate goal is to capture a page image rather than assert its responsive layout contract, ScreenshotNeo offers a one-request website screenshot API. It does not replace Galen’s spec-based layout assertions. For Galen setup and option details, use the ScreenshotNeo API 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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

ScreenshotNeo can accept cookie or consent banners like a visitor and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots, and every feature is on every plan.

Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.

11. Frequently asked questions

Does Galen require Selenium?

Galen uses Selenium to control browsers, select page elements, and inspect their dimensions and positions. Browser and driver setup is therefore part of a typical browser run.

Can Galen test more than one browser?

Yes. Galen documents local browser configuration and Selenium Grid configurations that specify browser parameters. Confirm the combinations supported by your current browser, driver, Selenium, and Galen versions.

Does Galen automatically know the correct responsive design?

No. You define the expected layout in specs and associate those expectations with viewports or tags.

Is Galen only for screenshots?

No. Screenshots can help diagnose failures, but the core layout workflow evaluates spec assertions about page elements and their geometry.

When should I use a screenshot API alongside Galen?

Use Galen when you need repeatable assertions about layout. A screenshot API is useful when you need to obtain an image or PDF without maintaining a browser automation setup; it does not by itself express Galen’s layout contract.