Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Add hook scope aliases `:example` and `:group` #297

Closed
wants to merge 1 commit into from
@fj
fj commented

As per a discussion on the mailing list, Evgeniy Dolzhenko suggested that if we were going to have aliases, it would be optimal to have a change that introduced the aliases of :example, and :group, to parallel the existing :suite alias.

Here is a change that does this.

@dchelimsky
Owner

FYI - I need to let this stew a bit before doing it. I'm personally a big fan, but I don't want to create confusion for many to ease confusion of few. Might be something to include in a 3.0 release, which I don't want to do for a while (probably not before 6 months since the 2.0 release). So I'm leaving this open for the moment.

@fj
fj commented

Sure thing; thanks, David.

@Peeja

Triage fairy here.

Do these years-old issues that are in the 3.0 milestone need to be bumped and re-discussed, or are they in 3.0 so people don't have to think about them for now and I should leave them alone?

@myronmarston

@Peeja -- thanks for helping triage issues!

I generally tag things as "3.0" so that we keep the ticket open (since it's a valid issue) but make it obvious we're not planning on addressing it before 3.0.

@EarthCitizen

:example and :group seem a lot clearer to me than :all and :each. I often have to explain to people the difference between them. :example and :group would require less explanation I think. More intuitive.

@JonRowe
Owner

Personally... I feel it's less intuitive, because we don't make clear what an example or a group is, (I know those are the names internally but this isn't test unit we don't expose those to people).

I'd support these aliases though, some folk will like them, some won't. I'd prefer :spec and :context over :example and :group... maybe...

@christhekeele

I'm actually pretty excited for this.

@samphippen
Collaborator

perhaps before(:each_spec) and before(:this_context)?

@samphippen
Collaborator

@JonRowe @soulcutter @myronmarston @alindeman what do you think about my names? I think it'd be good to close this one out sooner rather than later.

@soulcutter
Collaborator

I think I prefer before(:example) and before(:context) (a mix of the original suggestion and @JonRowe 's). I'm not sure it's worth fiddling with too much, though, so the original suggestion is just fine by me.

I will say don't like :each_spec or :this_context since they are wordier and just don't read as well with the underscores.

@samphippen
Collaborator

I think :example and :context is also good. @fj would you mind updating this to use those symbols?

@myronmarston

I think it's worth while to change the aliases if a majority of the community finds them to be more clear. However, there hasn't yet been a consensus: between the original mailing list thread and this discussion, there have been something like 8 different proposals for new aliases. I don't think there's enough consensus on this yet.

Personally, if we're going to change it, my vote would be for :example and :group. But as I said, I don't think we have a consensus yet.

@fj
fj commented

FYI, I'm happy to update the PR and will take ownership whenever you feel consensus has been reached.

@myronmarston How would you propose we discover what the consensus is? Straw poll on the mailing list?

@myronmarston

@myronmarston How would you propose we discover what the consensus is? Straw poll on the mailing list?

I think asking folks to comment here would be a good way to go about it. We can spread the word through twitter and the mailing list.

@fj
fj commented

OK, consider this comment the poll then.

There is a proposal to add sensible aliases for :each and :all to mirror the :suite alias. Please cast a vote for what you think aliases for :each and :all should be called:

  • :example and :group, respectively
  • :example and :context, respectively
  • :spec and :context, respectively
  • Something else (please specify)
  • I don't think we need aliases
@fj
fj commented

+1 for :example and :context.

@christhekeele

+1 for :example and :group.

@batasrki

If we need to add aliases, I'll +1 for :example and :group

@vothane

+1 for :example and :context.

@ywen

I might be biased but after so many years with each and all, I find example and group to be confusing. Seriously, if we want to do something in this area, why not just remove support for all?

@ywen

Ah didn't read about the vote comment. I vote for we don't need aliases. My reasoning is more aliases will just lead to more confusion.

@sferik

I’m not sure these aliases are necessary but I prefer :context to :group.

@cupakromer
Collaborator

No aliases.

Personally, I find the aliases to be more confusing. I may be biased from using :each and seeing :all for so long, but, to me they make a lot of sense.

If aliases are added, I would prefer :example and :context.

My reasoning boils down to the current DSL. example is already an alias for it. And context is starting to gain more usage.

:spec doesn't fit within the current DSL. Though it does match the name we've given to our tests when talking about them. I could also see it being a short reference to the other it alias specify. Though I've rarely seen specify used in practice. Based on this, I feel trying to mix a name (:spec) with a DSL keyword (:context) would just be a mind bender. Better to keep similar references by matching :spec with :group.

@JonRowe
Owner

example it and specify are all aliases for creating an Example they have equal priority at the moment however internally we consider it and specify to be aliases of example with specify being a legacy hangaround.

I've changed my mind and consider example and context to be the preferred additional labels here.

@samphippen
Collaborator

@myronmarston @JonRowe this one's gotten properly stale. My feeling based on this is that the conclusion was example and context were the right names if the aliases were added, and that there's an open question as to whether we should add these aliases. Thoughts?

@myronmarston
Owner

@samphippen -- I'm still mulling it over a bit. I almost closed this a while back as there wasn't real consensus; however, recently I've seen a couple situations where people were confused about this:

RSpec.configure do |config|
  config.before(:all) do
    # do something
  end
end

In the context of RSpec.configure, the :all scope is a bit confusing: given it's not in an example group, it sounds like it adds a hook that runs once, before all examples, but really it adds a before(:all) hook to each top-level example group. before(:suite) is the scope that runs before all examples once.

Given that, I'm now thinking that we should add the aliases, and example and context seem to be the winners. I think that :context is a lot more clear for the config case above than :all, anyway.

@fj
fj commented

I'm happy to update the pull request accordingly if you're on board with changing it to example and context, @myronmarston. The config case you describe is one of the areas that was discussed on the original mailing thread, iirc, and it was the one that personally appealed to me.

@samphippen
Collaborator

@fj that'd be great, if you could also rebase against master that'd be :sparkles:

@fj
fj commented

Well, sure. It'd be a a pretty lame commit if it wasn't against a rebased master. :)

@fj
fj commented

@myronmarston Just confirming: are you okay with example and context? If so I'll make a new PR.

@myronmarston

@myronmarston Just confirming: are you okay with example and context? If so I'll make a new PR.

:+1:

@samphippen
Collaborator

@fj just wanting to bump this. Are you still up for opening a new PR?

@fj
fj commented

Closing this one so that discussion can move to the other PR, #1174.

My mind's a little blown that I opened this original PR 3 years ago...

@fj fj closed this
@myronmarston

Thanks for sticking with us, @fj :). Sometimes it takes us awhile to come around...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Feb 2, 2011
This page is out of date. Refresh to see the latest.
Showing with 56 additions and 1 deletion.
  1. +12 −1 lib/rspec/core/hooks.rb
  2. +44 −0 spec/rspec/core/example_group_spec.rb
View
13 lib/rspec/core/hooks.rb
@@ -142,7 +142,18 @@ def scope_and_options_from(scope=:each, options={})
options = scope
scope = :each
end
- return scope, options
+ return normalized_scope_for(scope), options
+ end
+
+ def scope_aliases
+ @scope_aliases ||= {
+ :example => :each,
+ :group => :all,
+ }
+ end
+
+ def normalized_scope_for(scope)
+ scope_aliases[scope] || scope
end
end
end
View
44 spec/rspec/core/example_group_spec.rb
@@ -244,6 +244,50 @@ module RSpec::Core
end
describe "#before, after, and around hooks" do
+ describe "scope aliasing" do
+ it "aliases the `:group` hook scope to `:all`" do
+ group = ExampleGroup.describe
+ order = []
+ group.before(:group) { order << 1 }
+ group.example("example") {}
+
+ group.hooks[:before][:all].run_all(group)
+ order.should == [1]
+ end
+
+ it "aliases the `:example` hook scope to `:each`" do
+ group = ExampleGroup.describe
+ order = []
+ group.before(:example) { order << 1 }
+ group.example("example") {}
+
+ group.hooks[:before][:each].run_all(group)
+ order.should == [1]
+ end
+
+ it "should work with `before`" do
+ group = ExampleGroup.describe
+ order = []
+ group.before(:group) { order << 1 }
+ group.before(:example) { order << 2 }
+ group.example("example") {}
+
+ group.run
+ order.should == [1, 2]
+ end
+
+ it "should work with `after`" do
+ group = ExampleGroup.describe
+ order = []
+ group.after(:example) { order << 1 }
+ group.after(:group) { order << 2 }
+
+ group.example("example") {}
+
+ group.run
+ order.should == [1, 2]
+ end
+ end
it "runs the before alls in order" do
group = ExampleGroup.describe
Something went wrong with that request. Please try again.