It is hard to underestimate a value and importance of automated tests. Creating confidence about if the code works the right way and thus enabling safe refactoring is just one thing.

Opinionated Guide To Readable RSpec

I help our CTOs, Development Leads, Product Owners and business executives to design and build scalable and maintainable systems. With over 13 years of experience gained on software development projects delivered to international clients, I am able to enhance the productivity of software development teams while creating data collection, processing and analysis tools.

Błażej Kosmowski

### Importance of testing

It is hard to underestimate a value and importance of automated tests. Creating confidence about if the code works the right way and thus enabling safe refactoring is just one thing. Another one is that test suite can act as a way to document behavior and also, especially when approached the BDD way, can drive the code design and architecture. We cannot forget that tests are just a bunch of code, and as it is the case with any kind of code, those can be written in a better or worse way.

### There is only one way

The only way is a TDD way. Seriously. Obviously, there are many advocates of writing tests after implementation. It might feel that it is easier (sometimes it is) and faster (sometimes it also is) but the fact remains, it will backfire sooner or later. Usually if the feature or application we implement is really trivial, then writing tests for it might become an overkill. This is rarely a case though, as our apps tend to grow larger and larger and then we suddenly realize, we are missing the safety net in form of reliable test suite. Yet the sad fact is, that adding good quality tests after the implementation is much harder. Not only might we have already introduced a code (architecture) that is hard to test, but also reverse-engineering of all test cases we need to cover might be a very time consuming undertaking. What is more, it is an investment that might be hard to justify to our customer. To make the long story short, in this article we assume, that all new code introduced is driven by writing tests first.

### Outside-in (BDD) versus Inside-out

One of decisions we need to make when introducing a test suite to our application is to what tests to start with when implementing a new feature. Without going into too many details, there are two major approaches. The first one is to test “inside-out”, and thus focus on “how” — which is usually correlated with more up-front planning in relation to implementation and results in more low-level / unit testing. The second approach is so-called behavior driven development (testing “outside-in”) that more focuses on “why”. For this opinionated guide we will follow the BDD way, as it tends to put fewer constraints on actual implementation and results in smaller number of tests covering the same number of cases. Also it works better in the context of the next issue we are after — readability.

### DRY oriented versus readability oriented

Another decision to make before diving-in into writing tests is more closely related to code organization. A very common approach is to treat tests similarly to regular code, and optimize them as much as possible. Such optimization can involve using lots of shared code, abstractions, helper methods and so on. With this approach we can write tests quickly, efficiently keeping them compact at the same time, yet there is also one significant downside — reduced readability / intelligibility. Those tests might be totally understandable for us during the process of writing, but next time we see them and would like to untangle the context of each one it might become much more difficult, especially if it was not us who created those tests. It might be necessary to navigate through many places in and outside of given test file to sort out what some neat and tidy one liner actually verifies. I intend to present a slightly different approach that focuses on maximizing the readability of tests we write. Despite some costs correlated with such approach, I find resultant test suite to be much easier and pleasurable to work with.

### In pursue of readability

To sum up, our goal is to produce readable specs the BDD way. Vastly improving readability of tests we write is a matter of following a few simple rules.

**Identify the subject**
First step in identifying the subject is to realize what is the outermost layer of a feature we are going to implement. Usually this might be some user facing functionality — then we should consider `feature` or `view` specs to start with. If we just need to expose an API endpoint, then `request` or `controller` specs will be our starting point. If our job is to write some script, then maybe `rake`, `seed`, `datafix` or similar tests are the right way to go. Sometimes we will just end up writing some lower level unit tests first, but the important thing is to start at the highest reasonable level of abstraction. This way we will leave ourselves greater amount of freedom during the implementation phase and also it will be easier for us to specify initial expectations.

**Organize stages of test**
To improve readability of a given test, try to organize its code around three separate stages: setup, subject and assertions. This approach, also referred to as act-arrange-assert or given-when-then, suggests to put all code responsible for setting up context first, then execute the subject of a test and verify results as the last step. Separating those stages with a blank line will further help in visually identifying each of them.

<Gist id="22f40d69b3ab466bbf5feb713b35b279" />

**Keep everything in “it”**
This is where the readability oriented approach differs the most from the optimization oriented one. The key is to keep most, if not all code required to execute test within individual `it` block. This means that we should drop all usages of `let`, `subject` and `described_class` and significantly limit the usage of both filters (`before`, `around` and `after`) and shared contexts / examples. This means more code will be duplicated with tests setup growing. However, the key advantage is, that while reading a test, developer will be fully aware of the context and will immediately see how test setup affects assertions. With heavily optimized specs code it might require a lot of navigation within spec file and external files to fully understand the environment in which assertions are checked.

<Gist id="22f40d69b3ab466bbf5feb713b35b279" />

**Be explicit about data**
To make the process of identifying correlations between the test setup and the assertions easier, it might be beneficial to be as explicit about data as possible. One way is to limit the use of local variables, and just use explicit (yes, duplicated) values directly. Those values should also be more or less real in context of domain represented, i.e. assigning user the age of 200 isn’t a good idea. Furthermore, do only introduce a data to spec if it is actually relevant when asserting expectations — the less there is to grasp the easier it will be to comprehend the whole test. Also using tools like `ffaker` to generate fake, random data might be cool when seeding development database, but in specs it just adds ambiguity without introducing any significant advantages.

We should also resign from using fixtures in favor of using factories. Fixtures, usually stored in separate files, hide important context of spec, necessary to understand it to the fullest extent. One of exceptions to this rule is recording HTTP communication (i.e. using `vcr` gem) — if amount of data that needs to be stubbed is massive as in this case, it might be actually better to move it out from spec file and thus improve its readability.

<Gist id="bd7585e0a986fae589ef544ea02ab099" />

**Put extra effort in naming contexts and expectations**
Last but not least, we can waste our efforts outlined in previous points by not documenting our tests properly and effectively. There are three major blocks dedicated to documenting our tests: `describe`, `context` and `it`. `describe` helps us to define our subject — usually top-level describe is either a feature name or a class name, while lower level `describe` define methods, constants etc. To emphasize the type of the subject we are going to test, it might be useful to establish some ground rules related to naming.

* Prepend dot when testing class-level methods, i.e. `".send_notifications!"`
* Prepend hash when testing instance methods, i.e. `"#full_name"`
* Prepend colon when testing specific parts of hash, i.e. `":data"`
* Use upper case letters when describing consts, i.e. `"MAX_PROJECTS"`
* Use actual class names, when describing classes, i.e. `ProjectMembership`
* Use regular text, when describing features and everything else, i.e. `"User dashboard"`

Another documentation related block is `context`. Contexts should clearly describe… context (or environment) in which our assertions will be verified. It is a good practice to always start context descriptions with `“when”` and keeping those descriptions concise. Each context should describe only one aspect of environment (i.e. `"when a user is admin and current day is Sunday"` should be splitted into two nested contexts) and we should refrain from including contexts in expectations (i.e. it `"sends notification when email is provided"` should have `"when email is provided"` extracted to context).

Last block is `it`. We already know we should “keep everything in `it`”, but what is also important is proper description that defines what `it` means. The good practice is to use present simple tense to describe expectations and keep those expectations concise, precise and unambiguous. If expectations description is too long, it might indicate we test too much in one example and it might be a good idea to split it.

<Gist id="bac8b86c14bb3c80b94d95ae188e8dab" />

Also, given example clearly shows correlation between descriptions and stages of test.

![Img](https://a.storyblok.com/f/86602/800x543/9277928df8/1_godckzned4she72mm-_gqq-1.png)

### Wrap up

Focusing on tests readability does involve some costs, like code duplication and more constraints on how tests are composed. Benefits however, overweight those costs in my opinion, and we end up with much more comprehensible, maintainable and reliable test suite. Are we ultimately fated to write massive amounts of almost identical code though? Fortunately, there are a couple of techniques that will make your suite slimmer without sacrificing readability. Those will be tackled in [the second part of this article.](https://selleo.com/blog/an-opinionated-guide-to-readable-rspec-part-2-of-2)

It is hard to underestimate a value and importance of automated tests. Creating confidence about if the code works the right way and thus enabling safe refactoring is just one thing. Another one is that test suite can act as a way to document behavior and also, especially when approached the BDD way, can drive the code design and architecture. 

An Opinionated Guide To Readable RSpec (part 1 of 2)

In the [previous part](https://selleo.com/blog/an-opinionated-guide-to-readable-rspec-part-1-of-2) of this article we focused on making specs we try to write as readable as possible. This however, comes at a cost of duplication and bloated individual tests. While this is a cost we intend to pay, there are ways to mitigate the impact of readability oriented specs on the overall size of our suite.

### Reducing assertions phase LOC
Using custom matchers
Using custom matchers not only allows improving tests readability, but in many cases it also allows to slim down the assertions count. Custom matchers can originate from some ready to use libraries like [shoulda-matchers](https://github.com/thoughtbot/shoulda-matchers) or [rspec-json_expectations](https://github.com/waterlink/rspec-json_expectations) but nothing stops us from rolling our own solution.

**Using proper matchers**
Sometimes it is even unnecessary to introduce any new matchers to the project. Using the existing ones effectively can help in reducing the size of assertions section as well. For instance, to check whether the given result is a collection where order is not important, but includes objects of given class with given attributes we might use several separate assertions. It is possible to write one instead though, e.g.

<Gist id="11776d5dd9401562557b33f24c37e33a" />

**Using spies and message expectations to our advantage**
It is important to realize when to use [message expectations](https://relishapp.com/rspec/rspec-mocks/v/3-7/docs) (`expect(subject).to receive(:method)`) and when to use spies (`allow(subject).to receive(:method); expect(subject).to have_received(:method)`) while writing our specs. Even though act-arrange-assert way of composing a test is preferred, asserting message expectations using spies will not only make some specs bulkier, but may also make them less readable.

Always use spies if the correlation between mocked object and assertions is not clear — for instance, when testing `DestroyUser` service that should send a delayed user notification after the user is destroyed using some of separate service.

<Gist id="7f0b57b31285a1db3f660b71bbb59f6e" />

This way we maintain act-arrange-assert structure of a test and also explicitly ensure in assertions section that the expected behaviour was triggered. However, if the correlation between the setup and subject is already clear, then using regular message expectations seems to be a reasonable exception. In this case let’s consider testing a wrapper for some client library.

<Gist id="34713c75b5ec9a54ee777efa0725910f" />

The second assertion here is of very little value, as the only thing it checks is whether we called the client with correct argument list. We can already clearly see that the client was called as result attributes contain information from client’s response. Therefore, it feels reasonable to move arguments checking to mocking (setup) phase and drop last assertion.

<Gist id="476aac46f6ee179610b89686c91e9d79" />

### Reducing setup phase LOC
**Testing less edge cases within one example**
If we are after slimming down the setup phase of our spec, the simplest way to achieve that result is by reducing the amount of cases we want to verify and moving them to separate test. This can sometimes make tests more clear and comprehensible at a cost of larger suite.

<Gist id="6957ac2a0885b15691f62fc561cf954c" />

vs

<Gist id="ea9477218f5765ae16b60c15a1c383b5" />

**Hiding irrelevant setup in factories**
In some cases, explicitly creating certain objects in a setup phase of our test is of very little value in terms of showing correlations between setup and assertions. In such cases it might be a good idea to hide such objects creation in factories (using traits or other means).

<Gist id="167848730c34853fa8d6d92381985c6b" />

vs

<Gist id="bd63e8198f37e8f8e74dd08ab0dc7d07" />

**Hiding irrelevant setup in helper methods**
It happens that some parts of our spec seem to be irrelevant in terms of making the test understandable, but are too specific for given case to extract them to factories. Extracting such a code to a helper method living in the test itself can help make each test slimmer and more readable at the same time.

<Gist id="1ca06922030b720495986528bab32909" />

vs

<Gist id="183532104633b78916fd2b0aab651b08" />

**Introducing abstract setup definitions**
If the context we need to describe is very difficult to be expressed simply by creating objects and mocking interfaces, we may resort to even more sophisticated use of helper methods. Below we can find an example extracted from the real codebase.

<Gist id="9b2f09c831e93c30a2bf149b888bb477" />

Preparing such a complex context as the one represented in rates table above would require massive amount of stubbing or (if this data originates from external service) recording a vcr cassette, that would effectively hide all important knowledge from test setup. get_nightly_price_for method contains logic that parses the table and transforms it into JSON that would be originally returned from the external service. It also contains logic responsible for calling class being tested the proper way and returning the result.

Formatting code specifically for testing purposes
It is worth considering having different code formatting rules for tests. Rarely do we need to paste large hashes of data in actual codebase, while in specs the story is different. For instance, in the hash below it might be beneficial to keep several keys in one line, respecting only maximum line length, instead of dedicating a separate line for each individual key.

<Gist id="7c5270a244a476cb6be723c2e226e989" />

vs

<Gist id="7f38ac6af0cdf2cd4e4ff32a738fe4ff" />

**Excluding irrelevant data**
The most self-explanatory rule of all. Any data that is not relevant should be kept away from the test setup. It is not that intuitive in some cases though. For instance, when mocking responses from an API we need to decide if we want to use the whole response (that might be large and complex) or just a part of it that is useful in our scenario. When writing tests for client library, showing the whole response might be beneficial, whereas when writing tests for a wrapper, we might focus only on fields we actually use.

**Keeping integration testing under control**
The less we mock, the more we test at once. It is totally fine with BDD approach and helps in reducing the overall size of our test suite. Still, if the thing we test interacts with many objects across the whole system, the corresponding tests might require setting up those additional objects and thus effectively enlarging the setup section of such tests. There is no golden rule here, but if the setup section feels a bit too large in such case, mocking some part of the solution might be beneficial in resolving this problem.

### Reducing overall tests count and size
**Introducing helper methods for retrieving result of behavior**
If we realize that there is a pattern of how we trigger the tested behavior or retrieve its result, it might be worth considering to introduce one or a couple of helper methods facilitating this process and potentially reducing code responsible for that in each test. For instance, the following code:

<Gist id="fc649b26b114431d664309fdd658862f" />

could be rewritten to

<Gist id="1a97e9b8416f044156a692a71fb5e0b6" />

with a help of following module

<Gist id="506e6ec7221afe300a1d8e08b5cd4e68" />

**Multiple assertions per test**
Even though it is definitely not something pure-TDD followers would recommend, multiple assertions per one test can help in effectively reducing overall size of the test suite. It would be best to have those assertions correlated with one thing being tested, but it should not be a rule that cannot be broken. For instance, in controller specs testing that response is 200 OK, the changes to database were applied correctly and correct services were called with correct params all of these assertions are reasonable to be included in the same test sharing the same setup section.

**Testing things once only, unless necessary otherwise**
In BDD it is not natural to test same things twice, but sometimes it might be reasonable too. By default tests for all edge cases and non-major execution paths should be handled by lower-level tests in which it does not seem necessary to provide general testing as well. Default behaviour was tested by higher-level testing after all. Still, if some class becomes sort of “library” class that might be used directly in other parts of the system, it might be beneficial to provide a full unit-testing for such entity. This way potential user of such class will have a place in which he can check what are its capabilities and usage examples.

**Skipping low value tests**
Again, following BDD approach helps in skipping low value tests, but to restate — testing relations, attribute accessors, migrations and similar things do provide very little value and in many cases makes refactoring less comfortable. All of those aspects should be tested indirectly by some higher-level testing. This will save us a few lines of code as well.

**Testing multiple edge cases within one test**
Even though it contradicts recommendation related to reducing setup section size, testing multiple edge cases in one test can greatly reduce the total amount of tests and the size of a suite. It is a matter of finding the right balance and always taking readability concerns into account. The more edge cases we handle in one test, the more difficult it might be to find correlations between setup and assertions. Good test description might help, but only to some extent and not in all cases.

**Taking advantage of integration testing in all kinds of tests**
Last but not least, it is worth realizing how certain level of integration testing on all levels affects the size of the test suite. The more integration testing we allow in each spec, the less specs we will need altogether. Therefore, usually most of our tests beside the lowest-level ones are not isolated completely from underlying dependencies.

### Summary
Focusing on tests readability has a great impact on the size of those tests, which in turn can reduce the level of readability we fought so hard for. Having a couple of techniques described above in our toolbox can significantly help in mitigating this unwanted effect by making test suite slimmer and each test even more comprehensible.

In the previous part of this article we focused on making specs we try to write as readable as possible. This however, comes at a cost of duplication and bloated individual tests. While this is a cost we intend to pay, there are ways to mitigate the impact of readability oriented specs on the overall size of our suite.

Read our blog fueled by years of development experience

Business

Technology

Opinionated Guide To Readable RSpec

An Opinionated Guide To Readable RSpec (part 1 of 2)

An Opinionated Guide To Readable RSpec (part 2 of 2)

Tell us about your project