Describe/It statements should always be written in human-readable grammar.

Unit Tests: More Readable Describe/It Statements in Protractor/Jasmine

When writing any tests, we want our failures to be as human-readable as possible so that we can diagnose and solve the issue immediately.

In frameworks like Protractor and Jasmine, blocks of tests are written in a pattern of “describe/it”. These two lines are crucial elements in improving your testing workflow.

How to create human-readable test failures

I was taught to always follow the describe/it pattern of this thing / does this, respectively, so that it reads like a sentence.

This makes test failures REALLY easy to read. Think of it like writing a checklist that you’ll read later when something doesn’t get done.

So lets say we’re testing that a search box correctly filters an array of strings, we could say:

// Protractorjs in ES6
describe('the search function', () => {
  it('returns an array of strings that contain a given string', () => {
    [...insert test here...]
  }
})

When this test fails, the output will say:

FAIL: The search filter returns an array of results that contain a given string
Expected [the right thing], got [the wrong thing].

Which of course is just our describe and our it statements smushed together. So we know EXACTLY what failed, in plain speech, just by reading the output.

But what about multiple ‘it’s?

The same pattern can be applied!

describe('the search function', () => {
  it('returns an array of strings that contain a given string', () => {
    [...insert test here...]
  }
  it('returns an empty array when there are no matches', () => {
    [...insert test here...]
  }
})

When these both fail, they will return the following output:

FAIL: The search filter returns an array of results that contain a given string.
Expected [the right thing], got [the wrong thing].
FAIL: The search filter returns an empty array when there are no matches.
Expected [another right thing], got [another wrong thing].

Now everyone will think you’re super cool because your tests are actually readable. That’s what makes you cool these days, right?