Skip to content
This repository

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

Closed
wants to merge 1 commit into from
John Feminella
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.

David Chelimsky
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.

John Feminella
fj commented

Sure thing; thanks, David.

Peter Jaros

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?

Myron Marston

@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.

Jon Rowe
Collaborator

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...

Christopher Keele

I'm actually pretty excited for this.

Sam Phippen
Collaborator

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

Sam Phippen
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.

Bradley Schaefer
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.

Sam Phippen
Collaborator

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

Myron Marston
Owner

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.

John Feminella
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?

Myron Marston
Owner

@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.

John Feminella
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
John Feminella
fj commented

+1 for :example and :context.

Christopher Keele

+1 for :example and :group.

Srdjan Pejic

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

Thane Vo

+1 for :example and :context.

Yi Wen
ywen commented

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?

Yi Wen
ywen commented

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.

Erik Michaels-Ober
sferik commented

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

Aaron Kromer
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.

Jon Rowe
Collaborator

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.

Sam Phippen
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?

Myron Marston

@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.

John Feminella

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.

Sam Phippen
Collaborator

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

John Feminella

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

John Feminella

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

Myron Marston

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

:+1:

Sam Phippen
Collaborator

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

John Feminella fj closed this
John Feminella
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...

Myron Marston

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

Showing 1 unique commit by 1 author.

Feb 02, 2011
Add scope aliases ':example' => ':each' and ':group' => ':all' a48a406
This page is out of date. Refresh to see the latest.
13  lib/rspec/core/hooks.rb
@@ -142,7 +142,18 @@ def scope_and_options_from(scope=:each, options={})
142 142
           options = scope
143 143
           scope = :each
144 144
         end
145  
-        return scope, options
  145
+        return normalized_scope_for(scope), options
  146
+      end
  147
+
  148
+      def scope_aliases
  149
+        @scope_aliases ||= {
  150
+          :example => :each,
  151
+          :group => :all,
  152
+        }
  153
+      end
  154
+
  155
+      def normalized_scope_for(scope)
  156
+        scope_aliases[scope] || scope
146 157
       end
147 158
     end
148 159
   end
44  spec/rspec/core/example_group_spec.rb
@@ -244,6 +244,50 @@ module RSpec::Core
244 244
     end
245 245
 
246 246
     describe "#before, after, and around hooks" do
  247
+      describe "scope aliasing" do
  248
+        it "aliases the `:group` hook scope to `:all`" do
  249
+          group = ExampleGroup.describe
  250
+          order = []
  251
+          group.before(:group) { order << 1 }
  252
+          group.example("example") {}
  253
+
  254
+          group.hooks[:before][:all].run_all(group)
  255
+          order.should == [1]
  256
+        end
  257
+
  258
+        it "aliases the `:example` hook scope to `:each`" do
  259
+          group = ExampleGroup.describe
  260
+          order = []
  261
+          group.before(:example) { order << 1 }
  262
+          group.example("example") {}
  263
+
  264
+          group.hooks[:before][:each].run_all(group)
  265
+          order.should == [1]
  266
+        end
  267
+
  268
+        it "should work with `before`" do
  269
+          group = ExampleGroup.describe
  270
+          order = []
  271
+          group.before(:group) { order << 1 }
  272
+          group.before(:example) { order << 2 }
  273
+          group.example("example") {}
  274
+
  275
+          group.run
  276
+          order.should == [1, 2]
  277
+        end
  278
+
  279
+        it "should work with `after`" do
  280
+          group = ExampleGroup.describe
  281
+          order = []
  282
+          group.after(:example) { order << 1 }
  283
+          group.after(:group) { order << 2 }
  284
+
  285
+          group.example("example") {}
  286
+
  287
+          group.run
  288
+          order.should == [1, 2]
  289
+        end
  290
+      end
247 291
 
248 292
       it "runs the before alls in order" do
249 293
         group = ExampleGroup.describe
Commit_comment_tip

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.