Permalink
Browse files

Remove web_steps.rb. Release 1.1.0.

1 parent d7f33a8 commit f027440965b96b780e84e50dd47203a2838e8d7d @aslakhellesoy aslakhellesoy committed Sep 28, 2011
View
@@ -1,9 +1,9 @@
PATH
remote: .
specs:
- cucumber-rails (1.0.6)
+ cucumber-rails (1.1.0)
capybara (>= 1.1.1)
- cucumber (>= 1.0.6)
+ cucumber (>= 1.1.0)
nokogiri (>= 1.5.0)
GEM
@@ -97,7 +97,7 @@ GEM
bson (>= 1.3.1)
mongoid (2.2.1)
activemodel (~> 3.0)
- mongo (< 1.4, >= 1.3)
+ mongo (>= 1.3, < 1.4)
tzinfo (~> 0.3.22)
multi_json (1.0.3)
nokogiri (1.5.0)
@@ -152,7 +152,7 @@ GEM
sprockets (2.0.0)
hike (~> 1.2)
rack (~> 1.0)
- tilt (!= 1.3.0, ~> 1.1)
+ tilt (~> 1.1, != 1.3.0)
sqlite3 (1.3.4)
term-ansicolor (1.0.6)
thor (0.14.6)
View
@@ -1,3 +1,45 @@
+## [v1.1.0](https://github.com/cucumber/cucumber-rails/compare/v1.0.6...v1.1.0)
+
+### Removed features
+
+The following files will no longer be generated if you are running `rails generate cucumber:install`:
+
+* features/step_definitions/web_steps.rb
+* features/support/paths.rb
+* features/support/selectors.rb
+
+The reason behind this is that the steps defined in `web_steps.rb` leads people to write scenarios of a
+very imperative nature that are hard to read and hard to maintain. Cucumber scenarios should not be a series
+of steps that describe what a user clicks. Instead, they should express what a user *does*. Example:
+
+ Given I have signed up as "user@host.com"
+
+with a Step Definition that perhaps looks like this:
+
+ Given /^I have signed up as "([^"]*)"$/ do |email|
+ visit(signup_path)
+ fill_in('Email', :with => email)
+ fill_in('Email', :with => email)
+ fill_in('Password', :with => 's3cr3t')
+ fill_in('Password Confirmation', :with => 's3cr3t')
+ click_button('Sign up')
+ end
+
+Moving user interface details from the scenarios and down to the step definitions makes scenarios
+much easier to read. If you change the user interface you only have to change a step definition or two
+instead of a lot of scenarios that explicitly describe how to sign up.
+
+You can learn more about the reasoning behind this change at the following links:
+
+* [Cucumber mailing list: Removing web_steps.rb in Cucumber 1.1.0](http://groups.google.com/group/cukes/browse_thread/thread/26f80b93c94f2952)
+* [Cucumber-Rails issue #174: Remove web_steps.rb since it encourages people to write poor tests.](https://github.com/cucumber/cucumber-rails/issues/174)
+* [Refuctoring your Cukes by Matt Wynne](http://skillsmatter.com/podcast/home/refuctoring-your-cukes)
+* [Imperative vs Declarative Scenarios in User Stories by Ben Mabey](http://benmabey.com/2008/05/19/imperative-vs-declarative-scenarios-in-user-stories.html)
+* [Whose domain is it anyway? by Dan North](http://dannorth.net/2011/01/31/whose-domain-is-it-anyway/)
+* [You're Cuking it Wrong by Jonas Nicklas](http://elabs.se/blog/15-you-re-cuking-it-wrong)
+
+You can learn more about what Capybara has to offer in Capybara's [README](https://github.com/jnicklas/capybara).
+
## [v1.0.6](https://github.com/cucumber/cucumber-rails/compare/v1.0.5...v1.0.6)
### Bugfixes
@@ -3,14 +3,14 @@ $LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
Gem::Specification.new do |s|
s.name = 'cucumber-rails'
- s.version = '1.0.6'
+ s.version = '1.1.0'
s.authors = ["Aslak Hellesøy", "Dennis Blöte", "Rob Holland"]
s.description = "Cucumber Generators and Runtime for Rails"
s.summary = "#{s.name}-#{s.version}"
s.email = 'cukes@googlegroups.com'
s.homepage = "http://cukes.info"
- s.add_runtime_dependency('cucumber', '>= 1.0.6')
+ s.add_runtime_dependency('cucumber', '>= 1.1.0')
s.add_runtime_dependency('nokogiri', '>= 1.5.0')
s.add_runtime_dependency('capybara', '>= 1.1.1')
s.add_development_dependency('rails', '>= 3.1.0')
@@ -1,8 +1,7 @@
Feature: Allow Cucumber to rescue exceptions
- Background: A controller that raises an exception in a Rails app without web_steps.rb
+ Background: A controller that raises an exception
Given I have created a new Rails 3 app "rails-3-app" with cucumber-rails support
- And I remove the file "features/step_definitions/web_steps.rb"
And I write to "app/controllers/posts_controller.rb" with:
"""
class PostsController < ApplicationController
@@ -3,6 +3,20 @@ Feature: Capybara Javascript Drivers
Background: A simple calendar app
Given I have created a new Rails 3 app "rails-3-app" with cucumber-rails support
And I successfully run `bundle exec rails g scaffold appointment name:string when:datetime`
+ And I write to "features/step_definitions/date_time_steps.rb" with:
+ """
+ When /^(?:|I )select "([^"]+)" as the "([^"]+)" time$/ do |time, selector|
+ select_time(selector, :with => time)
+ end
+
+ When /^(?:|I )select "([^"]+)" as the "([^"]+)" date$/ do |date, selector|
+ select_date(selector, :with => date)
+ end
+
+ When /^(?:|I )select "([^"]+)" as the "([^"]+)" date and time$/ do |datetime, selector|
+ select_datetime(selector, :with => datetime)
+ end
+ """
Scenario Outline: Use a particular driver
Given I write to "features/create_appointment.feature" with:
@@ -8,9 +8,6 @@ Feature: Rails 3
Then the following files should exist:
| config/cucumber.yml |
| script/cucumber |
- | features/step_definitions/web_steps.rb |
| features/support/env.rb |
- | features/support/paths.rb |
- | features/support/selectors.rb |
| lib/tasks/cucumber.rake |
And the file "features/support/env.rb" should contain "require 'cucumber/rails'"
@@ -20,6 +20,12 @@ Feature: Mongoid
Scenario: Tests
When I go to the home page
"""
+ And I write to "features/step_definitions/web_steps.rb" with:
+ """
+ When /^I go to the home page$/ do
+ visit '/'
+ end
+ """
And I overwrite "features/support/env.rb" with:
"""
require 'cucumber/rails'
@@ -5,7 +5,6 @@ Feature: Multiple Databases
Background: A Rails 3 app utilizing multiple database repositories exists
Given I have created a new Rails 3 app "rails-3-app" with cucumber-rails support
- And I remove the file "features/step_definitions/web_steps.rb"
And I append to "config/database.yml" with:
"""
@@ -1,33 +0,0 @@
-Feature: Named Selectors
-
- Scenario: Look within named selector
- Given a project without ActiveRecord
- And a cukes resource
- And I write to "app/views/cukes/index.html.erb" with:
- """
- <div class="foo">foo</div>
- <div class="bar">bar</div>
- """
- And I write to "features/tests.feature" with:
- """
- Feature: Tests
- Scenario: Tests
- When I go to the cukes page
- Then I should see "foo" within the foo div
- And I should not see "bar" within the foo div
- """
- And I overwrite "features/support/selectors.rb" with:
- """
- module HtmlSelectorsHelpers
- def selector_for(locator)
- return '.foo' if locator == 'the foo div'
- end
- end
- World(HtmlSelectorsHelpers)
- """
- And I run `rake cucumber`
- Then it should pass with:
- """
- 1 scenario (1 passed)
- 3 steps (3 passed)
- """
@@ -1,24 +0,0 @@
-Feature: Pseudo-class Selectors
-
- Scenario: Look within css pseudo-class selectors
- Given a project without ActiveRecord
- And a cukes resource
- And I write to "app/views/cukes/index.html.erb" with:
- """
- <div>foo</div>
- <div>bar</div>
- """
- And I write to "features/tests.feature" with:
- """
- Feature: Tests
- Scenario: Tests
- When I go to the cukes page
- Then I should see "bar" within "div:nth-child(2)"
- And I should not see "foo" within "div:nth-child(2)"
- """
- And I run `rake cucumber`
- Then it should pass with:
- """
- 1 scenario (1 passed)
- 3 steps (3 passed)
- """
@@ -1,141 +0,0 @@
-Feature: Select dates
-
- Background: A simple calendar app
- Given I have created a new Rails 3 app "rails-3-app" with cucumber-rails support
-
- Scenario: Select date and time
- Given I successfully run `bundle exec rails g scaffold appointment name:string when:datetime`
- And I write to "features/create_appointment.feature" with:
- """
- Feature: Create appointments
- Scenario: Constitution on May 17
- Given I am on the new appointment page
- And I fill in "Norway's constitution" for "Name"
- And I select "2009-02-20 15:10:00 UTC" as the "When" date and time
- And I press "Create Appointment"
- Then I should see "Norway's constitution"
- And I should see "2009-02-20 15:10:00 UTC"
- """
- When I run `bundle exec rake db:migrate`
- And I run `bundle exec rake cucumber`
- Then it should pass with:
- """
- 1 scenario (1 passed)
- 6 steps (6 passed)
- """
-
- Scenario: Select date with label pointing to first select
- Given I successfully run `bundle exec rails g scaffold appointment name:string when:date`
- And I write to "features/create_appointment.feature" with:
- """
- Feature: Create appointments
- Scenario: Constitution on May 17
- Given I am on the new appointment page
- And I fill in "Norway's constitution" for "Name"
- And I select "2009-02-20" as the "When" date
- And I press "Create Appointment"
- Then I should see "Norway's constitution"
- And I should see "2009-02-20"
- """
- And I write to "app/views/appointments/_form.html.erb" with:
- """
- <%= form_for(@appointment) do |f| %>
- <div class="field">
- <%= f.label :name %><br />
- <%= f.text_field :name %>
- </div>
- <div class="field">
- <%= f.label :when, :for => "appointment_when_1i" %><br />
- <%= f.date_select :when %>
- </div>
- <div class="actions">
- <%= f.submit %>
- </div>
- <% end %>
- """
- When I run `bundle exec rake db:migrate`
- And I run `bundle exec rake cucumber`
- Then it should pass with:
- """
- 1 scenario (1 passed)
- 6 steps (6 passed)
- """
-
- Scenario: Select date when the order of fields is changed and label is set to the first select
- Given I successfully run `bundle exec rails g scaffold appointment name:string when:date`
- And I write to "features/create_appointment.feature" with:
- """
- Feature: Create appointments
- Scenario: Constitution on May 17
- Given I am on the new appointment page
- And I fill in "Norway's constitution" for "Name"
- And I select "2009-02-20" as the "When" date
- And I press "Create Appointment"
- Then I should see "Norway's constitution"
- And I should see "2009-02-20"
- """
- And I write to "app/views/appointments/_form.html.erb" with:
- """
- <%= form_for(@appointment) do |f| %>
- <div class="field">
- <%= f.label :name %><br />
- <%= f.text_field :name %>
- </div>
- <div class="field">
- <%= f.label :when, :for => "appointment_when_2i" %><br />
- <%= f.date_select :when, :order=>[:month, :day, :year] %>
- </div>
- <div class="actions">
- <%= f.submit %>
- </div>
- <% end %>
- """
- When I run `bundle exec rake db:migrate`
- And I run `bundle exec rake cucumber`
- Then it should pass with:
- """
- 1 scenario (1 passed)
- 6 steps (6 passed)
- """
-
- Scenario: Select correct date when scoped
- Given I successfully run `bundle exec rails g scaffold appointment name:string when:date`
- And I write to "features/create_appointment.feature" with:
- """
- Feature: Create appointments
- Scenario: Constitution on May 17
- Given I am on the new appointment page
- And I fill in "Norway's constitution" for "Name"
- And I select "2009-02-20" as the "When" date
- And I select "2009-03-20" as the "When" date within "#extra"
- And I press "Create Appointment"
- Then I should see "Norway's constitution"
- And I should see "2009-02-20"
- """
- And I write to "app/views/appointments/_form.html.erb" with:
- """
- <%= form_for(@appointment) do |f| %>
- <div class="field">
- <%= f.label :name %><br />
- <%= f.text_field :name %>
- </div>
- <div class="field">
- <%= f.label :when, :for => "appointment_when_1i" %><br />
- <%= f.date_select :when %>
- </div>
- <div class="actions">
- <%= f.submit %>
- </div>
- <% end %>
- <div id="extra">
- <%= label_tag 'extra_when_1i', 'When' %>
- <%= date_select "extra", "when" %>
- </div>
- """
- When I run `bundle exec rake db:migrate`
- And I run `bundle exec rake cucumber`
- Then it should pass with:
- """
- 1 scenario (1 passed)
- 7 steps (7 passed)
- """
Oops, something went wrong.

12 comments on commit f027440

@sleeptillseven

Sorry, don't get how the whole step definitions process works now. The error message is like in old day, but which files to create/edit now is a total mystery to me now. Could the error message be more explicit (with more information which file to edit now)?

@aslakhellesoy
Member

I don't think I understand what you mean by "step definitions process". What error message are you referring to?

@sleeptillseven

I was used to the old way. Now when I wrote the feature and get (correctly) RED, the "error" message tells me to add steps... etc. But I have no real idea where to put what. I couldn't find any examples how it's to be done the "1.1.0"-way. I really like cucumber, but wasn't able to work with it for some time, so my brain really doesn't know where and how to put stuff now. I put it the old way (creating web_steps.rb, and __feature_steps.rb), but as I understand your statements that's wrong.

@aslakhellesoy
Member

I'm trying to understand your case here.

a) If you have upgraded a Rails project from Cucumber-Rails pre-1.1.0 to 1.1.0 (by changing the Gemfile and rerunning rails g cucumber:install), then the existing web_steps.rb file will be left intact.

b) If you install Cucumber-Rails 1.1.0 into a Rails app that hasn't previously had Cucumber-Rails installed, a web_steps.rb file will not be generated.

Which case are you?

@mlambie
mlambie commented on f027440 Oct 1, 2011

In my case it is situation b) and the confusion comes from following the new Rails 3 In Action tutorials and the "Given I am on the homepage" step now failing. The tutorial expected that the step was supplied in web_steps.rb but it's now been removed.

@mattwynne
Member
@mlambie
mlambie commented on f027440 Oct 2, 2011

@mattwynne yeah that's the book. There's an argument that newbies will rely on web_steps.rb as a crutch, which I understand, but I think web_steps.rb goes a long way towards lowering the barrier for testing adoption amongst that group, and that's a bigger gain.

@mattwynne
Member
@sleeptillseven

@aslakhellesoy I'm case b) just like @mlambie. Unfortunately I'm a lazy dev, so I copy&paste the thing, which I know isn't your intention, for good reasons. But I couldn't find anything explainatory within minutes, so that's what I did. I have your and @mattwynne's book, could you give me a hint where I could look a good example of hoe to do it the "1.1.0"-way? Many thanks and cucumber is awesome!
Sorry, I'm a difficult customer ;)

@jbpros
Member
jbpros commented on f027440 Oct 2, 2011

I think we need to put some effort into writing some decent online tutorials to show this group how to do it the right way. It isn't hard when you know how.

+1 to that. I'd be glad to help.

Also, it would be nice to clarify what is Behaviour-Driven Development. It looks to me that for some, BDD has become a cooler name for TDD, a synonym for acceptance tests, integration tests, tests for people who can't write code. In my mind it's much more than programming techniques.

I think The Cucumber Book is going to help a lot for understanding the purpose of Cucumber and what is BDD in general. It seems like a great step forward to me.

But of course, not everyone is going to buy it (unfortunately ;)).

In that respect, the death of web steps is also a good thing.

To use Cucumber "right" (i.e. as a BDD tool), one has to understand that communication is essential and Cucumber's main goal is primarily about communication and secondarily about testing.

The cukes.info homepage mentions the word "test" at least 8 times while "behaviour" appears only once. Maybe it's time to think again about the words used to promote and document Cucumber. We're supposed to embrace the ubiquitous language concept: let's do that in our own documentation!

E.g. don't use the word "test", use "scenario": unconsciously it will probably have the effect of thinking more about Cucumber as an efficient way for expressing behaviour rather than a "testing tool".

My point is: Cucumber is pretty well known today and it should use that renown to foster higher BDD values and concepts. Actually, I think that message is already carried by Cucumber, but in a clumsy fashion. Of course, there are certainly fair and understandable reasons to that. But now that Cucumber has matured and knows its way, maybe it's time to focus on and improve its message.

@aslakhellesoy
Member

@mlambie, @mattwynne I'm not going to put any effort into extracting web_steps.rb into a separate gem. Anyone is free to do so, but it won't be hosted under the cucumber github organization.

Regarding the Rails 3 in Action book - I'd rather work with the authors on providing an erratum to it.

@pietia
pietia commented on f027440 Oct 27, 2011

Good move!

Please sign in to comment.