capybara_narrative: a language for readable, non-flaky Capybara tests

Engineers on my team were reluctant to write end-to-end tests with Capybara. The UI was complex enough that the relevant fields were hard to target reliably, which is the common cause of flaky tests.

My response was capybara_narrative: a simple language for describing pages, with the underlying XPath mappings to specific fields hidden inside a page-object description file rather than inline in the test itself.

“So that you could write easy-to-read tests, but also have precise mappings to fields on pages so that the tests wouldn’t be flaky.”

— Chris Dwan, interview, 2026-08-07

The repository has been public on GitHub since 2020, was last pushed to in April 2025, and its own description — “a page objects library for capybara that focusses on the narrative” — lines up with the account above. Unlike the Chime and Patient Wisdom entries, a reader doesn’t have to take this one on testimony alone: the code is there to look at.

https://github.com/radixhound/capybara_narrative