Introduction #

Capybara Test Helpers is a flexible testing library built on top of capybara, that encourages good practices based on encapsulation and reuse.

Write integration tests that everyone can understand, and leverage your Ruby skills to keep them easy to read and easy to change.

Get started, or check the API reference.

Features ⚡️ #

Locator Aliases work with every Capybara method, allowing you to encapsulate CSS selectors and labels, and avoid coupling tests with the implementation.

The entire Capybara DSL is available, and element results are wrapped automatically so that you can chain your own assertions and actions fluently.

A powerful syntax for assertions and convenient primitives for synchronization enable you to write async-aware expectations: say goodbye to flaky tests.

Conventions make it easier to provide great debugging capabilities.

Finally, since it's plain Ruby, you can leverage your existing skills to modularize code and keep tests in good shape.

Why 🤔 #

capybara is a great library for integration tests in Ruby, commonly used in combination with RSpec or cucumber.

Although cucumber encourages good practices such as writing steps at a high level, thinking in terms of the user rather than the interactions required, it doesn't scale well in a large project. Steps are available for all tests, and there's no way to partition or isolate them.

At the same time, Gherkin is very limited as a language, it can be very awkward to use when steps require parameters, and it's hard to find and detect duplicate steps, and very time consuming to refactor them.

In contrast, writing tests in RSpec has a very low barrier since Ruby is a joy to work with, but you are on your own to encapsulate code to avoid coupling tests to the current UI. Small changes to the UI should not require rewriting dozens of tests, but without clear guidelines it's hard to achieve good tests.

Design 📐 #

This library provides a solid foundation of simple and repeatable patterns that can be used to write better tests.

Its design is loosely based on the concepts of Page Objects and Testing Robots, with a healthy dose of dependency injection.

Capybara has a great DSL, so the focus of this library is to build upon it, by allowing you to create your own actions and assertions and call them just as fluidly as you would call find or has_content?.

This library works best when encapsulating common UI patterns in separate helpers, such as a FormTestHelper or a DropdownTestHelper, and then reusing them in page-specific test helpers to write higher-level tests that are easier to read and maintain.