A community-driven Capybara coding style guide
= Capybara Style Guide
:idprefix:
:idseparator: -
:sectanchors:
:sectlinks:
:toc: preamble
:toclevels: 1
ifndef::backend-pdf[]
:toc-title: pass:[
== Introduction
[quote, Officer Alex J. Murphy / RoboCop]
Role models are important.
ifdef::env-github[]
TIP: You can find a beautiful version of this guide with much improved navigation at https://capybara.rubystyle.guide.
endif::[]
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.
https://github.com/rubocop/rubocop[RuboCop], a static code analyzer (linter) and formatter, has a https://github.com/rubocop/rubocop-capybara[rubocop-capybara] extension, provides a way to enforce the rules outlined in this guide.
You can generate a PDF copy of this guide using https://asciidoctor.org/docs/asciidoctor-pdf/[AsciiDoctor PDF], and an HTML copy https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html[with] https://asciidoctor.org/#installation[AsciiDoctor] using the following commands:
asciidoctor-pdf -a allow-uri-read README.adoc
Install the rouge gem to get nice syntax highlighting in the generated document.
====
== 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 understand 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[[click-link-or-button-specificity]]
(corresponds to Capybara/ClickLinkOrButtonStyle)
=== But if you do use a generic click then use a consistent method[[click-link-or-button-consistency]]
(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[[negation-matcher-consistency]]
(corresponds to Capybara/NegationMatcher)
=== Be concise: don’t use redundant withins[[no-redundant-within-finds]]
(corresponds to Capybara/RedundantWithinFind)
=== Be specific: Use the most specific action rather than a generic action with parameters.[[specific-action]]
(corresponds to Capybara/SpecificActions)
=== Be specific: Use the most specific finder rather than a generic finder with parameters[[specific-finder]]
(corresponds to Capybara/SpecificFinders)
=== Be specific: Use the most specific matcher rather than a generic matcher with parameters[[specific-matcher]]
(corresponds to Capybara/SpecificMatcher)
=== Don’t use visible: false in Capybara finders, instead use a specific visibility symbol[[visibility-matcher-specificity]]
(corresponds to Capybara/VisibilityMatcher)
== Using Capybara with RSpec
=== Use have_css or have_xpath instead of have_selector[[dont-use-have-selector]]
(corresponds to Capybara/RSpec/HaveSelector)
=== Prefer using predicate matcher over using predicate method directly[[predicate-matcher-rather-than-method]]
(corresponds to Capybara/RSpec/PredicateMatcher)
== Related Guides
== 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 https://www.patreon.com/bbatsov[Patreon].
=== How to Contribute?
It’s easy, just follow the contribution guidelines below:
== License
image:https://i.creativecommons.org/l/by/3.0/88x31.png[Creative Commons License]
This work is licensed under a http://creativecommons.org/licenses/by/3.0/deed.en_US[Creative Commons Attribution 3.0 Unported License]
== Credit
TBC!
