Capybara Style Guide

Introduction

Role models are important.

— Officer Alex J. Murphy / RoboCop

Tip	You can find a beautiful version of this guide with much improved navigation at https://capybara.rubystyle.guide.

This Capybara style guide outlines the recommended best practices for real-world programmers to write code that can be maintained by other real-world programmers.

RuboCop, a static code analyzer (linter) and formatter, has a rubocop-capybara extension, provides a way to enforce the rules outlined in this guide.

You can generate a PDF copy of this guide using AsciiDoctor PDF, and an HTML copy with AsciiDoctor using the following commands:

# Generates README.pdf
asciidoctor-pdf -a allow-uri-read README.adoc

# Generates README.html
asciidoctor README.adoc

Tip	Install the rouge gem to get nice syntax highlighting in the generated document. gem install rouge

A Living Document

This guide is work in progress - trying to fill in the arguments by which the rubocop-capbyara cops were written so that users can undestand the tradeoffs on different approaches (whether to configure, enable or disable different cops) and understand where it’s a question of consistency and/or style, or are there other issues at play.

Using Capybara

Use a specific click_link or click_button to surface accessibility issues

(corresponds to Capybara/ClickLinkOrButtonStyle)

But if you do use a generic click then use a consistent method

(also corresponds to Capybara/ClickLinkOrButtonStyle)

Don’t set expectations on Capybara current_path

(corresponds to Capybara/CurrentPathExpectation)

Don’t use deprecated style methods

(corresponds to Capybara/MatchStyle)

Either use of have_no_* or use not_to consistently for negated expectations

(corresponds to Capybara/NegationMatcher)

Be concise: don’t use redundant withins

(corresponds to Capybara/RedundantWithinFind)

Be specific: Use the most specific action rather than a generic action with parameters.

(corresponds to Capybara/SpecificActions)

Be specific: Use the most specific finder rather than a generic finder with parameters

(corresponds to Capybara/SpecificFinders)

Be specific: Use the most specific matcher rather than a generic matcher with parameters

(corresponds to Capybara/SpecificMatcher)

Don’t use visible: false in Capybara finders, instead use a specific visibility symbol

(corresponds to Capybara/VisibilityMatcher)

Using Capybara with RSpec

Use have_css or have_xpath instead of have_selector

(corresponds to Capybara/RSpec/HaveSelector)

Prefer using predicate matcher over using predicate method directly

(corresponds to Capybara/RSpec/PredicateMatcher)

Related Guides

• Ruby Style Guide

• RSpec Style Guide

• Rails Style Guide

• Minitest Style Guide

Contributing

Nothing written in this guide is set in stone. Everyone is welcome to contribute, so that we could ultimately create a resource that will be beneficial to the entire Ruby community.

Feel free to open tickets or send pull requests with improvements. Thanks in advance for your help!

You can also support the project (and RuboCop) with financial contributions via Patreon.

How to Contribute?

It’s easy, just follow the contribution guidelines below:

• Fork the project on GitHub

• Make your feature addition or bug fix in a feature branch

• Include a good description of your changes

• Push your feature branch to GitHub

• Send a Pull Request

License

This work is licensed under a Creative Commons Attribution 3.0 Unported License

Credit

TBC!