Unify multiple-condition filtering

[myronmarston]

When applying metadata conditions for filltering (e.g. hooks, module inclusions, shared example group inclusion, define derived metadata, etc) we sometimes use an :all? semantic (for hooks) and sometimes an :any? semantic (for everything else). This is inconsistent and hard to explain to users. I don't think we ever consciously chose to make it diverge but we never sat down and thought through how we could have a unified semantic.

As part of #1796 I've thought about this quite a bit and I think it would be nice to unify the filtering. I'm leaning towards making it all? because it allows us to support both:

RSpec.configure do |c|
  # MyModule will only be included in groups with both `:foo => true` AND `:bar => true`
  c.include MyModule, :foo => true, :bar => true
end

#...but if you want the `any?` semantic, just call `include` twice:

RSpec.configure do |c|
  # MyModule will only be included in groups with either `:foo => true` OR `:bar => true`
  c.include MyModule, :foo => true
  c.include MyModule, :bar => true
end

In effect, you can think of each call to include as adding an entry to a metadata_filter_hashes array, and the logic winds up being:

if metadata_filter_hashes.any? do |hash|
  if hash.all? { |k, v| applies?(k, v) }
    do_it!
  end
end

If we were to standardize on any? semantics, I don't think there'd be any way for users to get the all? semantic when they wanted it.

This would be a breaking change and would have to go in 4.0, unless we wanted to introduce a config option sooner. I think this would be a pretty unobtrusive change for most users (as multi-condition filtering isn't often used).

We may also want to remove the :if and :unless filter support, as it adds complexity for little benifit over a normal ruby ifand unless.

[L2G]

Could this be the reason why I'm seeing --example options nullify --tag options, even when I'm explicitly setting both on the command line?

[myronmarston]

Could this be the reason why I'm seeing --example options nullify --tag options, even when I'm explicitly setting both on the command line?

No, that's for a different reason: --example is given higher priority than exclusion filters. The idea being that a user may have this config:

RSpec.configure do |c|
  c.filter_run_excluding :slow
end

Examples tagged with :slow would normally be excluded, but the user can manually opt-in to an example using --example flag.

--tag CLI options are similarly trumped by --example, although perhaps they shouldn't be. We don't currently differentiate between tag filters set in ruby via c.filter_run_excluding and --tag...

[maxlinc]

--tag CLI options are similarly trumped by --example, although perhaps they shouldn't be. We don't currently differentiate between tag filters set in ruby via c.filter_run_excluding and --tag

Is there a workaround to this? Am I forced to use --pattern / --exclude-pattern instead of tags if I want to run by --example but exclude a certain type of tests (slow, integration, etc)?

[myronmarston]

Am I forced to use --pattern / --exclude-pattern instead of tags if I want to run by --example but exclude a certain type of tests (slow, integration, etc)?

It depends on what you are trying to do. --pattern/--exclude-pattern operate at the file level (selecting or rejecting matched files from being loaded) so it doesn't give you the granularity that other forms of metadata filtering provide.

Anyhow, as for a better workaround: I'd suggest re-organizing your examples so that the ones you'd normally want to exclude (slow, integration, whatever) are put in another file or directory. Then it's very easy to control things by passing directories to rspec. I've greatly benefitted from having spec/unit, spec/integration and spec/acceptance directories; that way I can run the large set of fast unit specs with rspec spec/unit, or opt-in to including a smaller set of slower integration specs by adding spec/integration or pick just acceptance specs or whatever.

[xaviershay]

this seems good to me, including removal of if and unless options.

[pirj]

@JonRowe Do you want me to work on this for RSpec 4?

[JonRowe]

Sure, it seems a reasonable addition, we should probably convert our specs off if/unless to :skip => <boolean> if/unless <msg> first as this is compatible with both branches, then make the behaviour change on top of that.