Effective Testing with RSpec 3, Structuring Code Examples

Notes from Effective Testing with RSpec 3, chapter 7.

In Chapter 7 we go in-depth on the different ways of organizing code and making specs readable.

“…readable specs are crucial for communicating your ideas and for long-term maintainability. They show the intent behind the code.”

Excerpt From: Myron Marston, Ian Dees. “Effective Testing with RSpec 3”

Ways of organizing specs

  # Use a class.
  RSpec.describe Class do

  # Use an object.
  RSpec.describe object do

  # Provide more context in a string.
  RSpec.describe object, 'an interface' do

  # Add a tag for configuring in Hooks and filtering.
  RSpec.describe Class, 'an adapter library', issue: ABC-123 do
  
  RSpec.describe 'a class' do
    # `context` is an alias for `describe`.
    context 'in this environment' do
      it 'does one thing'
      it 'does another'
    end
    
    describe 'data structure' do
      # `example` is an alias for `it`.
      example 'in ordered form'
      example 'in unordered form'
    end
    
    describe 'api config' do
      # `specify` is an alias for `it`.      
      specify 'initializer fails when api is not defined'
      specify 'APIClient.gem specifies dependencies'
    end
  end

If the above aliases are not enough to make your specs readable you can add your own aliases. Create an alias on groups or examples and add metadata for filtering.

Ways of Sharing Logic

This section is mostly review of what we already know.

• let method, which uses memoization.
• hooks, run code for setup & teardown. Hooks can happen on examples, groups, the entire suite, or configured for tags.
• Helper methods, regular ruby method, to reduce complexity.
• Modules, regular ruby module, to reduce complexity.
• Sharing Context and Examples to share code in the test context.

We have to be careful when sharing code in our test suites. Remember that it’s not production code. If I sacrifice readability and maintainability for optimization it is a step backward not forward.

Specs should be modular. When it fails we should have everything we need to understand the failure in front of us to resolve the issue.

Refactoring Exercise

I was a little ambitious in my refactoring. After comparing my first refactoring to the books example I realized I had missed the point. The goal of our test suit is to be easy to read in the code and execution.

This is the rspec output of my first attempt. I extracted ‘behaves like Parser’ to share between the specs.

Addressable::URI
  parses the scheme
  parses the path
  behaves like Parser
    identifies schemes
      host
      port

URI
  behaves like Parser
    identifies schemes
      host
      port
  port
    defaults http to 80
    defaults https to 443

It doesn’t read very well as each line is missing context. We cannot randomly pick up a line and understand what we are testing. We have to scan up to know what is happening. The next refactoring has better readability.

Addressable::URI
  parses the scheme
  parses the path
  behaves like a URI Parser
    identifies the host
    identifies the port

URI
  behaves like a URI Parser
    identifies the host
    identifies the port
  port
    defaults http to 80
    defaults https to 443

I’ve uploaded my refactoring to GitHub.