Define derived metadata.

[myronmarston]

This fixes #969 and supercedes #1089.

Not ready for merge yet (or even at a point where I'd ask it to be reviewed)...I'm pushing this so I can make an rspec-rails PR that depends on this.

[JonRowe]

Ping me when you'd like a review ;)

[myronmarston]

Ping...this is ready for review.

I'm not totally satisfied with the name define_derived_metadata. It's a general callback mechanism for metadata that doesn't necessarily have to be used to define derived metadata (all though that's the use case there). Not sure of a better name, though. Any thoughts?

[JonRowe]

Why if filter.empty? here?

[myronmarston]

Because if you don't pass any filters, it should always apply:

RSpec.configure do |config|
  config.define_derived_metadata do |metadata|
    # this block should always run against every metadata hash
  end
end

[JonRowe]

Oh, to apply the block globally, I see.

[JonRowe]

Figured it out as you commented there ;)

[JonRowe]

I like how simple this has turned out, how about define_dynamic_metadata BTW?

[myronmarston]

Oh yeah, the other open question is the semantics of passing multiple filters to define_derived_metadata: should the callback only get invoked when a metadata hash matches all passed filters or any of them? any_apply is used for module inclusion filtering and example filtering. all_apply is used for hook filtering. This seems the closest to module inclusion so I aligned it with that. Any preferences?

[myronmarston]

how about define_dynamic_metadata BTW?

I think I like define_derived_metadata better but I have no objective reason for that preference.

[JonRowe]

I didn't know we used any_apply? for module inclusion, that's strangely inconsistent in my eyes.
I've only used example filtering via tags which are any_apply? for each --tag but all_apply? for csv (at least I think it's that way round).

I think I have a minor preference for all_apply? for parity with hooks...

[JonRowe]

I'm actually ok with define_derived_metadata but you asked for suggestions ;)

[myronmarston]

I didn't know we used any_apply? for module inclusion, that's strangely inconsistent in my eyes.

Well, that was the necessary semantic for rspec-rails to be able to use its old way of inclusion:

https://github.com/rspec/rspec-rails/blob/533660d10d2beeb586d99641c6b0cc280a642e05/lib/rspec/rails/example.rb#L16-L18

RSpec::Rails::ControllerExampleGroup would be included if it was in spec/controllers or if tagged with :type => :controller; it didn't require both. That makes sense to me.

I think any is a slightly better semantic because it seems more flexible...if you want the semantic to actually be all, you can still get it:

config.define_derived_metadata(:a => 1, :b => 2) do |metadata|
  if metadata.values_at(:a, :b) == [1, 2]
    # mutate metadata
  end
end

...but you can't as easily simulate the any behavior if rspec's semantic is all.

[myronmarston]

Good to merge?

[yelled3]

although, I like to be able to do this, i find the syntax somewhat confusing... it seems like the 2nd line overrides the first.
how do you see this being used?

it seems to me that it would be easier to have a single derived_metadata hash, which you can just edit...

c.update_metadata { |m| m[:b1_desc] = m[:description] + " (block 1)" }
c.update_metadata { |m| m[:b2_desc] = m[:b1_desc]     + " (block 2)" }

[JonRowe]

@yelled3 this is mainly being used for rspec-rails magic to prevent mutation of the hash pre runtime.

[JonRowe]

Good to merge?

Apart from one final thought, and that's that we should now prevent the metadata hash being mutated conventionally... (Even if we just dup it where it's accessed similarly to config.formatters)

[myronmarston]

Apart from one final thought, and that's that we should now prevent the metadata hash being mutated conventionally... (Even if we just dup it where it's accessed similarly to config.formatters)

Hmm...I'm on the fence about that. While it's a good idea to document the fact that we recommend not mutating metadata, consider the idea that rspec-rails has been doing so for years, and until you dug into rspec/rspec-rails#825, we had never seen any problems caused by metadata mutation....so in the vast majority of cases, it works fine. I think it's more likely to confuse to users to silently ignore any mutation they've done (which would happen if we used dup) than it is that they'd run into one of the cases where mutation caused a problem.