Use `with` and `describe_instance_method`

Want specs that look like this? Read on.

describe ServiceObjectUnderTest do
  describe_instance_method :a_long_and_descriptive_method do
    method_parameters(:subscription_class, :value)

    with subscription_class: :enterprise do
      with(value: 10).it { is_expected.to eq(0) }
      with(value: 8).it { is_expected.to eq(8) }
    end

    with subscription_class: :enterprise_plus do
      with(value: 11).it { is_expected.to eq(11) }
      with(value: 2).it { is_expected.to eq(2) }
    end
  end
end

Like most of America, lately I've been trying Marie Kondo's method of tidying up around my house. Around the Aha! codebase, I've likewise been trying to get my specs to spark joy. This week, I was working on some code that looked something like this:

class ServiceObjectUnderTest
  # Obviously oversimplified and contrived logic. Not the point of this exercise
  def a_long_and_descriptive_method(subscription_class, value)
    if subscription_class == :enterprise_plus
      value
    else
      value % 10
    end
  end
end

I was hacking some specs together for it, and came up with something like this:

require './service'

describe ServiceObjectUnderTest do
  describe '.a_long_and_descriptive_method' do
    it "returns modulo when not E+" do
      expect(
        described_class.new.a_long_and_descriptive_method(
          :enterprise,
          10
        )
      ).to eq(0)

      expect(
        described_class.new.a_long_and_descriptive_method(
          :enterprise,
          8
        )
      ).to eq(8)
    end

    it "returns the value when E+" do
      expect(
        described_class.new.a_long_and_descriptive_method(
          :enterprise_plus,
          11
        )
      ).to eq(11)

      expect(
        described_class.new.a_long_and_descriptive_method(
          :enterprise_plus,
          2
        )
      ).to eq(2)
    end
  end
end

I don’t know about you, but I get pretty grumpy when my tests are 8 times longer than the method I’m trying to specify. Not exactly joyful.

Don't repeat described_class everywhere

The first step here is to extract out the incredibly verbose method call:

require './service'

describe ServiceObjectUnderTest do
  describe '.a_long_and_descriptive_method' do
    subject(:described_method) do
      described_class.new.method(:a_long_and_descriptive_method)
    end

    it "returns modulo when not E+" do
      expect(
        described_method.call(:enterprise, 10)
      ).to eq(0)

      expect(
        described_method.call(:enterprise, 8)
      ).to eq(8)
    end

    it "returns the value when E+" do
      expect(
        described_method.call(:enterprise_plus, 11)
      ).to eq(11)

      expect(
        described_method.call(:enterprise_plus, 2)
      ).to eq(2)
    end
  end
end

This is a little better. I like the trick of using .method() to grab the method under test. Even just this small enhancement gives me a lot less typing.

But there’s still some repetition here: I have to repeat the method name a couple of times, and I have to keep typing out described_method. Since I’m using an explicit subject, I also don’t get to write short, punchy, self-documenting expectations. Additionally, I don’t get any hint from the spec what those parameters actually are. It would be nice to have that be self-documenting as well.

Writing our own descriptors

Let’s go one level deeper, by adding some methods to rspec’s example group.

require './service'

module RspecExtensions
  def describe_instance_method(method_name, &block)
    describe "##{method_name}" do
      let(:described_method) do
        described_class.new.method(method_name)
      end

      instance_eval(&block)
    end
  end
end

RSpec::Core::ExampleGroup.send(:extend, RspecExtensions)

describe ServiceObjectUnderTest do
  describe_instance_method :a_long_and_descriptive_method do
    subject { described_method.call(subscription_class, value) }

    context do
      let(:subscription_class) { :enterprise }

      context do
        let(:value) { 10 }
        it { is_expected.to eq(0) }
      end

      context do
        let(:value) { 8 }
        it { is_expected.to eq(8) }
      end
    end

    context do
      let(:subscription_class) { :enterprise_plus }
      context do
        let(:value) { 11 }
        it { is_expected.to eq(11) }
      end

      context do
        let(:value) { 2 }
        it { is_expected.to eq(2) }
      end
    end
  end
end

We're inserting our own macro here to avoid repeating the name of the method (in case we want to change it in the future). It also gives us a subject block that immediately tells us the method signature. While it's not obvious with this example, my experience is that using context and let also makes it really, really easy to add new test cases. If I think of some new edge cases that I want to test, I just have to drop a new expectation into the right section of the file, with all the other variables that are already put together.

A better way to add context

Our code is still pretty verbose, since we have to define a new context and a new let for each parameter value we want to test. Let’s write a macro for that. We'll add this to our RspecExtensions module:

  def with(lets, &block)
    context_description = lets.map{|k, v| "#{k}=#{v}"}.join(',')
    context("with #{context_description}") do
      lets.each do |lk, lv|
        let(lk) { lv }
      end

      instance_eval(&block)
    end
  end
end

Now, our specs look like this:

describe ServiceObjectUnderTest do
  describe_instance_method :a_long_and_descriptive_method do
    subject { described_method.call(subscription_class, value) }

    with subscription_class: :enterprise do
      with(value: 10) { it { is_expected.to eq(0) } }
      with(value: 8) { it { is_expected.to eq(8) } }
    end

    with subscription_class: :enterprise_plus do
      with(value: 11) { it { is_expected.to eq(11) } }
      with(value: 2) { it { is_expected.to eq(2) } }
    end
  end
end

Now we’re getting somewhere. Our tests are short and expressive, and basically all the boilerplate is gone.

Everything is better with curry

Having the subject there is nice, but now I'm thinking it could be better. What if instead of telling rspec that my subject is the invocation of my method with certain parameters, I could just tell it what those parameters were?

  def method_parameters(*parameters)
    let :method_called_with_parameters do
      parameters.inject(described_method.curry) do |curry, parameter|
        curry.call(send(parameter))
      end
    end

    subject { method_called_with_parameters }
  end

The curry method doesn't show up outside of code-golf often but it's pretty cool. It allows you to do partial application in ruby. As a result - I don't have to declare my subject explicitly anymore. I just have to call method_parameters(:subscription_class, :value), and everything just works.

The way I've written it here, there's also let(:method_called_with_parameters). This is so I can do something like this, if I'm testing for side effects:

expect { method_called_with_parameters }.to change(Feature. :count).by(1)

I'm also not crazy about that weird { it { condition } } block ; it looks like a busted handlebars template. Honestly, if I wasn’t writing a blog post about it, I'd leave it as it is. But since we’re here, let's refactor our with method. I want to be able to give it a block (in which case it should do exactly what it does now), or call .it directly on it to give it a one-line expectation. The only real way to do that is to use a proxy object:

  class WithProxy
    def initialize(example_group, lets)
      @example_group = example_group
      @lets = lets
    end

    def context_description
      @lets.map{ |k, v| "#{k}=#{v}"}.join(',')
    end

    def call(&block)
      lets = @lets
      @example_group.context("with #{context_description}") do
        lets.each do |lk, lv|
          let(lk) { lv }
        end

        instance_eval(&block)
      end
    end

    def it(&block)
      call { it(&block) }
    end
  end

  def with(lets, &block)
    proxy = WithProxy.new(self, lets)

    if block
      proxy.call(&block)
    else
      proxy
    end
  end

The big pay-off

With that little bit of weirdness out of the way, check out our end result:

require './service'
require './final_rspec_with_extensions'

describe ServiceObjectUnderTest do
  describe_instance_method :a_long_and_descriptive_method do
    method_parameters(:subscription_class, :value)

    with subscription_class: :enterprise do
      with(value: 10).it { is_expected.to eq(0) }
      with(value: 8).it { is_expected.to eq(8) }
    end

    with subscription_class: :enterprise_plus do
      with(value: 11).it { is_expected.to eq(11) }
      with(value: 2).it { is_expected.to eq(2) }
    end
  end
end

Now THIS sparks some joy. I don’t have to include anonymous contexts, and I can use with in two different, powerful ways. I can use it as a combination context and let to introduce multiple examples. I can also immediately call .it to get a one-line expectation with an implicit subject.

I get a beautiful, self-evident description of what the method should do in a variety of circumstances. I'll admit, I've never really been a TDD guy before - but something like this makes TDD a snap. Writing these specifications is quick, clean, and painless.

This is the output I get from running the above example, which is also very readable.

$ rspec --format=documentation 05_one_line_with_proxy.rb

ServiceObjectUnderTest
  #a_long_and_descriptive_method
    with subscription_class=enterprise
      with value=10
        should eq 0
      with value=8
        should eq 8
    with subscription_class=enterprise_plus
      with value=11
        should eq 11
      with value=2
        should eq 2

Conclusion

Hacking together the improvements to the specs above didn't take that long, and now we have some powerful new tools for writing clean, joyful specs. They're faster to write, easier to read, and easier to add to in the future. Take some time to optimize your code for developer happiness, and you may just find a huge productivity boost as a result.

If you want to find the whole extension that I wrote for this post, you can get it over at my github.