Galen Framework: Automated Layout and Responsive Testing

Most test automation frameworks are built for functional testing — clicking buttons, filling forms, verifying text. Layout and responsive design testing is a different problem. When a button overlaps the navigation at 375px wide, or a sidebar disappears at 768px, functional tests won't catch it.

Galen Framework was built specifically for this problem.

What Is Galen Framework?

Galen is an open-source testing framework for layout and responsive design testing. Instead of asserting that an element exists or contains certain text, Galen spec files describe spatial relationships between elements:

• "The navigation should be above the content"
• "At mobile breakpoint, the sidebar should not be visible"
• "The button should be inside the header with 10px margin on all sides"

Galen runs these specs against a real browser (via WebDriver), resizing the viewport to test each breakpoint.

Installation

Galen requires Java 11+. Install via the script:

# On Mac/Linux
curl -L https://raw.githubusercontent.com/galenframework/galen/master/install.sh | bash

# Verify
galen --version

Or via npm (wrapper):

npm install -g galenframework-cli

Your First Spec

Galen spec files use a custom DSL. Create specs/homepage.gspec:

@objects
  header        #header
  nav           #main-nav
  hero          .hero-section
  footer        footer

= Desktop Layout =
  @on *
    header:
      inside viewport 0px top, 0px left, 0px right
      height 60 to 80px
    nav:
      inside header 10px left, 10px right
      aligned horizontally all header
    hero:
      below header 0px
      width 100% of viewport/width

= Mobile Layout =
  @on mobile
    nav:
      visible false
    hero:
      width 100% of viewport/width
      below header 0px

Run the spec:

galen check specs/homepage.gspec \
  --url https://example.com \
  --size 1280x800 \
  --include "Desktop Layout" \
  --htmlreport reports/

The Galen Spec Language

Object Definitions

The @objects section maps names to CSS selectors:

@objects
  logo          .site-logo
  search        input[type="search"]
  results       #search-results
  result-*      .result-item     # matches multiple elements

The result-* pattern creates indexed references: result-1, result-2, etc.

Layout Assertions

Galen's spatial assertions cover every relationship you'd want to test:

sidebar:
  inside viewport 0px left
  below header 20px
  width 280px
  height 100% of viewport/height minus 80px

content:
  right-of sidebar 20px
  width > 60% of viewport/width
  aligned horizontally top sidebar

Common assertions:

Responsive Testing with Tags

Tags let you define which assertions apply at which breakpoints:

@set
  desktop_width 1280
  tablet_width  768
  mobile_width  375

@objects
  nav            #main-nav
  mobile-menu    .hamburger-menu

= Navigation =
  @on desktop, tablet
    nav:
      visible true
    mobile-menu:
      visible false
  
  @on mobile
    nav:
      visible false
    mobile-menu:
      visible true
      width 44px
      height 44px

Run at different sizes:

# Desktop
galen check specs/nav.gspec --url https://example.com --size 1280x800 --include desktop

# Mobile
galen check specs/nav.gspec --url https://example.com --size 375x812 --include mobile

JavaScript API

Galen also supports a JavaScript test format for more complex scenarios:

// tests/homepage.test.js
load('init.js');

forAll([
  { name: 'Desktop', size: '1280x800', tags: ['desktop'] },
  { name: 'Tablet',  size: '768x1024', tags: ['tablet']  },
  { name: 'Mobile',  size: '375x812',  tags: ['mobile']  }
], function(device) {
  test('Homepage layout on ' + device.name, function() {
    var driver = createDriver('https://example.com', device.size);
    checkLayout(driver, 'specs/homepage.gspec', device.tags);
    driver.quit();
  });
});

Run:

galen test tests/homepage.test.js --htmlreport reports/

Authentication and Login

For testing authenticated pages, use Galen's JavaScript API to handle login first:

test('Dashboard layout', function() {
  var driver = createDriver('https://app.example.com/login', '1280x800');
  
  // Log in
  driver.findElement(By.id('email')).sendKeys('user@example.com');
  driver.findElement(By.id('password')).sendKeys('secret');
  driver.findElement(By.css('button[type=submit]')).click();
  
  // Wait for dashboard
  driver.wait(until.elementLocated(By.id('dashboard')), 5000);
  
  // Now check layout
  checkLayout(driver, 'specs/dashboard.gspec', ['desktop']);
  driver.quit();
});

HTML Reports

Galen generates detailed HTML reports showing:

• Which specs passed/failed
• Screenshots at the tested viewport size
• Visual highlighting of elements that failed assertions
• The exact measured values vs expected values

galen test tests/ --htmlreport reports/ --testngreport reports/testng.xml

The visual diff output is one of Galen's most useful features — you can see exactly which element is out of place and by how many pixels.

CI Integration

GitHub Actions

name: Layout Tests

on: [push, pull_request]

jobs:
  layout:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Java
        uses: actions/setup-java@v3
        with:
          java-version: '11'
          distribution: 'temurin'
      
      - name: Install Galen
        run: |
          curl -L https://raw.githubusercontent.com/galenframework/galen/master/install.sh | bash
          echo "$HOME/.galen" >> $GITHUB_PATH
      
      - name: Install ChromeDriver
        uses: nanasess/setup-chromedriver@v2
      
      - name: Run layout tests
        run: galen test tests/ --htmlreport reports/ --parallel-tests 4
      
      - name: Upload reports
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: galen-reports
          path: reports/

When to Use Galen

Galen is a good fit when:

You have complex responsive designs. The more breakpoints and layout variations you need to test, the more value Galen's spec language provides.

Layout bugs reach production often. If developers regularly break layouts when adding features, a Galen suite catches regressions before merge.

You need to document layout intent. Galen specs are human-readable documentation of how the UI is supposed to look at each breakpoint.

Your team isn't using a component system. Storybook with Chromatic catches visual regressions at the component level. Galen is better for full-page layout validation.

Limitations

Learning curve on the spec language. The Galen DSL is unique — there's no crossover from other testing frameworks. Your team will need time to learn it.

Not for visual pixel-perfect testing. Galen verifies spatial relationships, not exact visual appearance. For screenshot comparison, use Percy or Applitools.

Slow at scale. Running the full test suite against multiple breakpoints can be slow without parallelization. Plan for this in CI time budgets.

Smaller community. Galen is less actively maintained than some alternatives. Issues can go unresolved for extended periods.

Galen vs Alternatives

For teams that care specifically about responsive layout correctness — not visual pixel-perfect matching, but structural layout — Galen fills a gap that other tools don't.

Summary

Galen Framework solves a specific problem: automating the validation of responsive layouts. Its spec language maps directly to what designers and developers talk about — element positions, visibility at breakpoints, spatial relationships.

If layout regressions are a recurring pain and you don't want to maintain pixel-perfect screenshots, Galen's approach is worth evaluating. The spec files double as living documentation of your responsive design intent.