Currently the world of integration testing is overwhelmed with complexity. Industry standards require adding more layers of abstraction with tools like Cucumber, SitePrism, and others, and as a result it becomes more difficult and tedious for a developer to write a simple test. But as any other part of the codebase, testing scenarios should be simple and fun. They should be designed for readability and changeability.<\/p>\n
In this article, I\u2019m going to talk about how to make integration testing simple and effective with bare-bones Capybara. We will walk through several rules which, in my experience, lead to clarity and simplicity.<\/p>\n
Let\u2019s start with an example:<\/p>\n
scenario \"looking for a hotel\" do\r\n visit \"\/search\"\r\n should_see \"Type a destination\"\r\n fill_in \"Country\", with: \"France\"\r\n fill_in \"City\", with: \"Paris\"\r\n set_date \"02\/17\/2099\"\r\n select \"1\", from: \"Rooms\"\r\n select \"2\", from: \"Adults\"\r\n check \"I'm travelling for work\"\r\n click_on \"Search\"\r\n should_see \"1 result found\"\r\n should_see \"Test hotel\"\r\nend<\/pre>\nThat is an awesome testing scenario for a few reasons: Any developer with knowledge of the Capybara API can easily read it; it\u2019s obvious what it tests and what it expects, so it\u2019s easy to add more steps and change it; and it doesn\u2019t need changing when markup changes. It only depends on the business requirements.<\/p>\n
Now, this scenario has some distinctive features: \u2013 There are no selectors. \u2013 All values are checked globally. \u2013 It tries to maximize usage of Capybara helpers (it sticks to simple means). \u2013 It extends the Capybara API with
should_see<\/code>, which is a helper that improves readability. \u2013 It also uses a custom helperset_date<\/code>, which is not scenario-specific but rather widget-specific \u2014 a helper for a date selector widget.<\/p>\nSo how do you make all your tests concise and to-the-point like this one? I\u2019ve come up with several rules that can help keep your tests focused on their job, as well as make them easy to write and change.<\/p>\n
Define a Limited Language<\/h2>\n
It\u2019s a good thing to take a user\u2019s perspective into account when you\u2019re writing tests. It allows you to focus on the end result and see the product as your user sees it. That\u2019s why you need an extra level of abstraction, a DSL that speaks in a user\u2019s terms.<\/p>\n
You could use Cucumber<\/a>, but even with that, it\u2019s easy to write steps like
When I click on \".my-form button\"<\/code>. In this case, you break the abstraction anyway, and now you have to deal with the mental overhead that Cucumber gives you, with nothing in return.<\/p>\nIn my experience, it\u2019s best to go with bare-bones Capybara. Note that Capybara already has this layer of abstraction. Think
click_on \"Purchase\"<\/code> versusfind(...).click<\/code>. The first one searches for an element by text and will refuse to click if it\u2019s not visible or if it\u2019s not a link\/button. It also reads nicely.<\/p>\nOf course that might not be enough, and you probably will need to implement your own custom steps. Just make sure they\u2019re on the same level of abstraction as
click_on<\/code>,fill_in<\/code>, and so on. They should not accept selectors, only text. For example, here\u2019s my most useful helper:<\/p>\ndef should_see(text)\r\n expect(page).to have_content(text)\r\nend\r\n\r\ndef should_not_see(text)\r\n expect(page).to have_no_content(text)\r\nend<\/pre>\nUse Universal Steps<\/h2>\n
By \u201cuniversal steps,\u201d I mean steps that get used in different tests, as opposed to feature-specific steps that only make sense within a certain scenario. Feature-specific steps should be avoided because they add up to mental overhead that a developer needs to deal with when working with a scenario.<\/p>\n
Instead, be explicit. Think about
fill_in_order_form<\/code> versusfill_in \"quantity\". with: ''; fill_in password with ''<\/code>. The former hides the complexity, and thus forces a developer to look into an implementation. The latter makes it explicit and easily accessible, so you should always be using it.<\/p>\nAvoid Using Selectors<\/h2>\n
When you use selectors, you switch your mindset from a user\u2019s perspective to a developer\u2019s, from feature to implementation. That\u2019s the wrong way to do it. Users don\u2019t think in selectors. They don\u2019t care about ids and classes. There\u2019s no value in it, nor they are visible to the user.<\/p>\n
What selectors do give you is an extra dependency on the code markup, which is an implementation detail. Now your test is going to fail not only because of an actual bug, but also because markup has changed for whatever reason. And it\u2019s not just that tests become fragile; they become harder to read and comprehend, and therefore harder to maintain.<\/p>\n
Compare:<\/p>\n
within(\".order-form\") do\r\n click_on \"input[type=submit]\"\r\nend<\/pre>\nand<\/p>\n
click_on \"Purchase\"<\/pre>\nNote how I just don\u2019t care where exactly on the page the button is located. There\u2019s nothing wrong with looking for elements globally \u2014 remember, that\u2019s how a user does it.<\/p>\n
Use Text Values<\/h2>\n
Try to always stick to something that a user can see on the page, like text values. It\u2019s really not as hard as it seems. First of all, Capybara out-of-the-box gives you tools that work this way, methods like \u201cclick_on\u201d (link and button values), \u201cfill_in\u201d (labels and placeholders), and so on. But even if you need something custom, it\u2019s actually quite easy to implement.<\/p>\n
By the way, this is why I don\u2019t use tools like SitePrism<\/a>. SitePrism allows you to map entities to selectors on the page and work with those entities instead of selectors directly. However, it\u2019s not solving a problem, it\u2019s just hiding it by adding another layer of abstraction. To my mind, that\u2019s even worse, because it makes the problem implicit.<\/p>\n
Deal with Ambiguity<\/h2>\n
As I said earlier, there\u2019s nothing wrong with searching for an element on a page globally. But what if there are several buttons on the page with the same title?<\/p>\n
Consider for a little bit that maybe this ambiguity should be addressed in the business area. How do you expect a user to behave when he sees two Purchase buttons? (A rhetorical question, of course.)<\/p>\n
There can be repetitive elements on a page (think rows in a table). One solution for this could be introducing new ids or classes to the page in order to be able to target them. But that\u2019s not a good way to do it. A better solution would be to depend on the order and use numerables in your test. Consider something like this:<\/p>\n
scenario do\r\n # ...\r\n within_table_row(3) do\r\n click_on \"Delete\"\r\n end\r\n # ...\r\nend\r\n\r\n# support\/helpers.rb\r\ndef within_table_row(position)\r\n row = find_all(\"table tr\")[position]\r\n within(row) do\r\n yield\r\n end\r\nend<\/pre>\nHaving a proper semantic markup also helps. For example, if you use the
aside<\/code> HTML tag for the menu block andmain<\/code> for the main content<\/a>, you can easily implement helpers likewithin_sidebar { ... }<\/code> andwithin_main { ... }<\/code>.<\/p>\nStick to Semantic Markup<\/h2>\n
The method
click_on<\/code> works perfectly for buttons and links, but it won\u2019t click on a span, for example. This is by design. You shouldn\u2019t have spans that behave like links in your code anyway. Use proper markup or ask your HTML developer to do so. If it\u2019s clickable, it should be a button or a link. If it\u2019s a form, it should be aform<\/code> element.<\/p>\nHTML is semantic for a reason, and browsers know better how to deal with different elements in your DOM when they know what they\u2019re dealing with.<\/p>\n
Another example of this kind is the method
fill_in<\/code>, which can handle both labels and placeholders. If your markup lacks this element, you may be tempted to usefind(\"input\").set<\/code>.<\/p>\nBut consider for a minute, maybe this is actually a UX problem? If there are no placeholders, nor labels on the page, how is the user to decide what should be put in that field and why? Instead of hacking your way through broken markup, consider changing it by adding a placeholder or a label.<\/p>\n
Conclusion<\/h2>\n
In general, never forget that testing should be simple and fun. I often find myself thinking about how can I make the experience even more enjoyable, and I hope you do, too. When you do achieve a certain level of clarity and simplicity in your testing scenarios, it pays off tremendously.<\/p>\n
\n