Geb and Grails for practical accessibility testing
Geb gives Groovy developers a readable way to drive a real browser, while Grails supplies the application, controllers, services and database behind it. Together, they turn user journeys into functional tests instead of isolated markup checks. That distinction matters for accessibility: a control may appear labelled in source code yet still be awkward to reach, announce or operate with a keyboard. Browser-driven checks can preserve those interactions as repeatable regressions.
Using Geb with Grails to validate accessibility basics works best when automated checks and human judgement have different jobs. Geb and Spock can verify landmarks, accessible names, focus movement, error states and browser behaviour; people still need to judge whether wording, alternative text and focus order make sense. For Australian teams, WCAG 2.2 AA is a practical target, particularly when public-sector work must meet the Australian Government Digital Service Standard.
Build a reliable Geb test harness
Geb pairs naturally with Spock’s specification style, allowing a browser scenario to read much like a user story. Put the automation libraries in the test source set and pin versions that match the Grails, Groovy and browser stack. The dependency roles are straightforward:
testImplementation "org.gebish:geb-spock:$gebVersion"
testRuntimeOnly "org.seleniumhq.selenium:selenium-chrome-driver:$seleniumVersion"
Use a driver already supported by your CI image, and avoid copying an example whose versions conflict with the application build. Geb configuration should also distinguish local development from continuous integration. A typical local configuration might look like this:
class GebConfig extends AbstractGebConfig {
static default = {
driver = { new ChromeDriver() }
waiting = {
timeout = 5
retryInterval = 0.5
}
}
}
Provide the base URL through environment-specific configuration so the same specification can run against a local Grails server, a shared test environment or a deployed preview. A short waiting timeout catches broken flows quickly, while Geb’s retry behaviour handles minor rendering delays without making every assertion unnecessarily slow.
Fixtures should create only the records a scenario needs and remove them predictably. If a browser test creates a customer, booking or order, call a fixture service rather than inserting database rows directly from the specification. This guide to a transactional service layer explains how to keep transactional methods separate from browser interactions. Avoid holding a database transaction open while waiting for a page: the test should complete the user action, verify the result and then clean up.
Check meaningful page structure
A Geb page object gives each screen a stable place to describe its important regions and controls. It also prevents specifications from depending on every detail of the HTML. For example, a contact page can expose its heading, main region and form without making the test repeat the complete DOM structure:
class ContactPage extends Page {
static url = "$baseUrl/contact"
static at = { $("h1").text() == "Contact us" }
static content = {
main { $("main") }
contactForm { $("form#contact") }
}
}
Use those definitions to assert structural conventions that native HTML should provide. Check for a unique page title, a declared document language, one clearly identifiable main region and a sensible heading hierarchy. Native landmarks such as header, nav, main and footer are generally more dependable than a collection of generic containers. A skipped heading level may not violate every WCAG criterion, but it can make content harder to navigate with a screen reader.
Automated structure checks are only signals, not complete accessibility decisions. A heading can be present but empty, a link can have an accessible name that makes no sense and a landmark can appear in the wrong place. Review the rendered page as well as the source. For Australian applications, the same checks should account for en-AU, Australian English spelling such as “organisation”, $ with an AUD amount, Australian postcode and state fields, and dates displayed as day, month and year. These details affect both screen-reader pronunciation and the usefulness of assertions against real content.
Test keyboard access and focus
Keyboard operation is one of the strongest reasons to use browser automation for accessibility. A Geb scenario can open a page, move through interactive elements and record the focused element, but expected results should still come from a native HTML or ARIA pattern. An element with a positive tabindex is not automatically usable if its DOM position conflicts with the visual order. Prefer controls in their natural source order and avoid positive tabindex values unless a documented interaction requires them.
Focus indicators need an explicit check too. Use the browser’s focus state to confirm that each interactive element can receive focus, then verify that the indicator remains visible against the surrounding colours. The focus sequence should reach links, buttons, fields, checkboxes and dialog controls without becoming trapped. For dynamic content, verify where focus goes after an error is created or a modal closes. If a validation summary receives focus, it should point to controls with keyboard-operable links rather than becoming a dead end.
Automation cannot judge the complete experience of a screen-reader user. Testing with VoiceOver, NVDA and other relevant assistive technologies remains part of the release process, particularly for users in Sydney and Melbourne as well as regional and remote communities using different devices and connection speeds. A teammate’s casual “have a look” at the keyboard flow can identify an obvious trap, but it cannot replace a structured test. Results also need an agreed severity scale rather than an invented percentage. The same discipline appears in this rating comparison: categories must be defined before scores can be compared meaningfully. Record the browser, viewport and tested flow beside each accessibility result.
Validate forms and error messages
Forms are where accessible names, instructions and state changes meet real user expectations. For every input, select and textarea, verify that it has a programmatic label through a native label, aria-labelledby or an appropriate aria-label. A placeholder is not a replacement because it disappears when the user begins typing. Also check that each field has a visible name, required fields are identified without relying only on colour, and instructions appear before the control they describe.
Error handling needs both structural assertions and realistic wording. A test can confirm that an invalid submission creates an error message, associates it with the relevant field and prevents submission. It should also check that focus moves to an error summary when appropriate, that summary items link to their fields and that the message explains how to correct the problem. For Australian addresses, use autocomplete tokens such as postal-code and country with the value AU where supported. Labels should make date expectations explicit: “Date of birth, for example 14/03/1990” communicates the local day-month-year format better than an unexplained sequence of boxes.
Visual presentation and non-form content belong in the same suite. Automated tools can flag many contrast failures, but people must inspect gradients, images and overlaid text. Check support for 200 per cent text resizing, reflow at narrow widths and a minimum target size. Meaningful images need suitable alternative text, while decorative images need an empty alternative. Captions and transcripts are necessary for recorded training content. Use ARIA only when native HTML cannot provide the required behaviour, because an incorrect role or state can make a page less accessible rather than more.
Make accessibility checks part of delivery
Geb can complement a scanner such as axe-core without treating that scanner as the final authority. Inject the axe-core script through WebDriver, execute it after the relevant page has loaded and fail the build for agreed, severe violations. The script can identify missing labels, invalid ARIA attributes and several contrast problems. It cannot determine whether alternative text communicates the purpose of an image, whether instructions are understandable or whether a focus sequence feels coherent.
Before adding parallel browser workers, give the test suite its own database and connection settings. Review Grails datasource configuration before pointing tests at shared infrastructure. A dedicated test datasource prevents accidental access to production data, while a deliberately sized connection pool keeps parallel specifications from exhausting available connections. Let each spec create uniquely named data and clean it through services or a controlled database reset rather than relying on whichever test happened to finish first.
Continuous integration should publish evidence that Australian stakeholders can review. A useful report records the WCAG target, tested user journeys, browser and operating-system versions, viewport sizes, automated findings, manual checks and unresolved exceptions. Run the most stable critical paths on every build, then extend browser coverage for releases. Public-sector and enterprise buyers in Australia often need a clear audit trail, so attach the report to the build result and link each confirmed issue to its severity and affected page. Keep known limitations visible; a green pipeline means the defined checks passed, not that the entire application has been certified accessible.
Create the first Geb suite around one critical Grails journey, such as login, checkout or a contact form. Capture the keyboard path, verify the page structure, exercise an error state and run the same specification in continuous integration. Review the rendered result with a screen reader before treating the checks as complete.
Your next pull request can begin the accessibility feedback loop: add one focused Geb specification, publish its report beside the build results and make the failed assertions visible to the whole delivery team.