Welcome to

Evaluate Expression

Home / TDD / Learning Tests

Learning Tests

I originially came across the concept of Learning Tests in Uncle Bob’s Clean Code. Since then I have put them to good use but have found that some devs find the distinction between “just testing a library” and Learning Tests to be unclear.

The main advantages I see of writing Learning Tests are as follows:

  • To test drive your understanding of a new library
  • Catch any breaking changes, based on your usage, when upgrading a library
  • Document your usage of a library
  • Gain confidence in swapping out libraries

To show this I’ve set up an example project, found here, to demo the process of testing a chosen library and then swapping it out. The simple use case is representing a domain model in JSON.

First implementation: Json4S

I deliberately first chose a library I hadn’t used before. A quick tour of JSON libraries in Scala by Manuel Bernhardt enabled me to find out about the methods of Json4s that I cared about.

An initial run of the tests was met with failure as I had missed the necessary import implicit val formats = DefaultFormats. Finding this during initial testing meant that I won’t run into this problem when writing my src code.

By writing these tests before src implementation I have limited my knowledge onboarding of the functions of the library to just the minimum of what I want to use.

My intended usage of Json4s is now documented. It is up to me to keep this documentation up to date with any additional functionality I make use of.

In the future if I were to upgrade the version of Json4s, the tests would highlight any breaking changes to me. API changes would result in compilation failures which would be easy to see in the smaller context of a test versus src code. Furthermore the running of the tests would bring to light any functional changes under the hood of the library.

Aren’t you just testing the library?

In essence the answer is yes. In all the teams I’ve worked in an early barrier to using an open source library is by first looking at its test coverage and usage by other companies. So in writing Learning Tests I am actually re-testing the library!

Given the level of testing, with the above code as an example, the time invested in writing these Learning Tests is immediately beneficial in understanding and documentation. Down the line having coverage when upgrading the library gives confidence to stay up to date with the latest changes.

Swapping out libraries

I’ve heard about this other library, Circe. I want to try it out.

I’ve written the same tests for the Circe library. The run of the tests reminded me that parse(greyhoundJson).getOrElse(Json.Null).as[Greyhound] returns an Either. Discovering this in the tests once again saved me from having to deal with the issue in the src code.


If I’m currently spiking which library to use my decision might come down to which library is easier to work with, both in terms of the src code I will write and the tests I already have written. Often, but not always, I am able to make this decision after having written the Learning Tests.

Are Learning Tests for me?

If you rely on open source libraries, then yes I would recommend Learning Tests.

If you work on an established project where the libraries are fixed and there is hesitancy to upgrade or change implementations, Learning Tests might be exactly what you need to gain the confidence to make these changes. If there is still no budge to change then keeping these tests may not be of any use anymore.

If you can think of any specific reasons why not to use Learning Tests, let me know and I’ll update this post.

Advanced usages of Learning Tests

If performance is a key concern, Learning Tests can be used to profile libraries. When a decision is made there is still value in keeping the Learning Tests of the other implementations, provided these are clearly identified as such and the dependencies is scoped to test only. By keeping these tests you can upgrade all of the possible solutions to see if one has made improvements in this area.

If you can think of any other benefits or usages of Learning Tests, let me know and I’ll update this post.

2 thoughts on “Learning Tests”
  1. Liam May 11, 2018on12:37 pm Reply

    Another thing worth mentioning is that this is a way to facilitate communication in a team. If Dave learns library X alone he might become the “X guru” aka “X bottleneck”. By writing down his learnings in code, other team members can quickly get up to speed on all the ugly bits when introducing a new technology by looking at his learning tests.

    You could also argue that, if your learning tests end up better than the official tests/documentation, you should push them upstream!

Leave a Reply

Your email address will not be published. Required fields are marked *

Thanks for reading!

>> <<