Building better descriptions with `when` and `while` contexts in addition to `with`

[joeldrapper]

I’d like my test description to say something like this and I’m struggling to fit it into the describe / with blocks:

Phlex::Component#render when rendering another component with a text content block it produces the correct output

I think we could achieve this by adding a when context method in addition to with.

describe Phlex::Component do
  describe "#render" do
    when "rendering another component"
      let(:another_component) { ... }
      
      with "a text content block" do
        let(:example) { ... }
        
        it "produces the correct output" do
          expect(output).to be == "..."
        end
      end
    end
  end
end

I think we should consider adding while while we're at it. For example, we might want a test that's described:

Phlex::Component#render when rendering another component with a text content block while in production it produces the correct output

[ioquatix]

describe blocks should be used for defining a subject.

describe String do
  let(:string) {"Hello World"}
end

I copied is_expected from RSpec but I am not sure about it. All the terminology is current tense but that is past tense and it looks odd in the output. I might remove it.

I've been using with for methods, e.g. with '#render'. The with block can take local scoped arguments, e.g. with 'a timeout', timeout :1 do ....

when seems to combine "noun + verb", i.e. when 'rendering another component' is similar to with 'another component' + some kind of method name somewhere.

It feels like maybe with and when are similar, e.g.

describe Phlex::Component do
  when invoking: '#render' do
    it "generates text output" ...
  end
end

Since while is used for loops in Ruby, I think we can't redefine it?

[ioquatix]

i.e. it would be nice if we could capture semantic value with the when block.

describe String do
  instance(:string) {"Hello World"}

  when invoking: :reverse do
    it {is_expected.to be == "dlroW olleH"}
  end
end

I think we want to avoid getting too specific for one use case, but this is a reasonably common pattern.

[ioquatix]

I ended up removing is_expected as it felt like a 2nd testing methodology which clashed with "present tense assertions".

I'm still open to having a specific clause for methods. What I currently write is with '#render' or with 'reversed #render' or something. Not sure if we can improve on that?

It's also a little tricky because sometimes you want to write without '#render'. But no such convention exists.

I'm open to ideas but I'd like to keep the set of concepts as small as possible.