spreewald 0.1.1 → 0.1.2

data/README.md

@@ -28,58 +28,426 @@ Alternatively, you can require everything by doing
 
     require 'spreewald/all_steps'
 
+## Waiting for page load
+
+Spreewald's web steps are all aware, that you might run them with a Selenium/Capybara webdriver, and wait for the browser to finish loading the page, if necessary.
+
+This is done, by rerunning any assertions until they suceed, or a timeout is reached.
+
+You can achieve this in your own steps by wrapping them inside a `patiently do` block, like
+
+    Then /^I should see "([^\"]*)" in the HTML$/ do |text|
+      patiently do
+        page.body.should include(text)
+      end
+    end
+
+More info [here](https://makandracards.com/makandra/12139-waiting-for-page-load-with-spreewald).
+
 ## Steps
 
-For a complete list of steps you have to take a look at the step definitions themselves. This is just a rough overview.
+### development_steps.rb
+
+
+
+* **Then it should work**
+
+  Marks scenario as pending
+
+
+* **Then debugger**
+
+  Starts debugger
+
+
+* **@slow**
+
+  Waits 2 seconds after each step
+
+
+* **@single**
+
+  Waits for keypress after each step
+
+
+
+### email_steps.rb
+
+
 
-### [development_steps](/makandra/spreewald/blob/master/lib/spreewald/development_steps.rb)
+* **When I clear my emails**
 
-Some development steps. Supports
+  
 
-* `Then debugger`
-* `Then it should work`       (marks step as pending)
-* `@slow-motion` (waits 2 seconds after each step)
-* `@single-step` (waits for keyboard input after each step)
 
+* **Then (an|no) e?mail should have been sent with:**
 
-### [email_steps](/makandra/spreewald/blob/master/lib/spreewald/email_steps.rb)
+  Example:
+  
+        Then an email should have been sent with:
+          """
+          From: max.mustermann@example.com
+          To: john.doe@example.com
+          Subject: Unter anderem der Betreff kann auch "Anführungszeichen" enthalten
+          Body: ...
+          Attachments: ...
+          """
+  
+  You can skip lines, of course.
 
-Check for the existance of an email with
 
-    Then an email should have been sent with:
-        """
-        From: max.mustermann@example.com
-        To: john.doe@example.com
-        Subject: Unter anderem der Betreff kann auch "Anführungszeichen" enthalten
-        Body: ...
-        Attachments: ...
-        """
+* **When I follow the (first|second|third)? link in the e?mail**
 
-You can obviously skip lines.
+  Only works after you have retrieved the mail using "Then an email should have been sent with:"
 
-After you have used that step, you can also check for content with
 
-    And that mail should have the following lines in the body:
-      """
-      Jede dieser Text-Zeilen
-      muss irgendwo im Body vorhanden sein
-      """
+* **Then no e?mail should have been sent**
 
-### [table_steps](/makandra/spreewald/blob/master/lib/spreewald/table_steps.rb)
+  
+
+
+* **Then I should see "..." in the e?mail**
+
+  Checks that the last sent email includes some text
+
+
+* **Then show me the e?mails**
+
+  Print all sent emails to STDOUT.
+
+
+* **Then that e?mail should have the following lines in the body:**
+
+  Only works after you've retrieved the email using "Then an email should have been sent with:"
+  
+  Example:
+  
+        And that mail should have the following lines in the body:
+          """
+          All of these lines
+          need to be present
+          """
+
+
+* **Then that e?mail should have the following body:**
+
+  Only works after you've retrieved the email using "Then an email should have been sent with:"
+  Checks that the text should be included in the retrieved email
+
+
+
+### table_steps.rb
 
 Check the content of tables in your HTML.
 
 See [this article](https://makandracards.com/makandra/763-cucumber-step-to-match-table-rows-with-capybara) for details.
 
+* **Then I should( not)? see a table with the following rows( in any order)?**
+
+  
+
+
 
-### [timecop_steps](/makandra/spreewald/blob/master/lib/spreewald/timecop_steps.rb)
+### timecop_steps.rb
 
 Steps to travel through time using [Timecop](https://github.com/jtrupiano/timecop).
 
 See [this article](https://makandracards.com/makandra/1222-useful-cucumber-steps-to-travel-through-time-with-timecop) for details.
 
-### [web_steps](/makandra/spreewald/blob/master/lib/spreewald/web_steps.rb)
+* **When the (date|time) is "(\d{4}-\d{2}-\d{2}( \d{1,2}:\d{2})?)"**
+
+  Example:
+  
+        Given the date is "2012-02-10"
+        Given the time is "2012-02-10 13:40"
+
+
+* **When the time is "(\d{1,2}:\d{2})"**
+
+  Example:
+  
+        Given the time is "13:40"
+
+
+* **When it is (\d+|a|some|a few) (seconds?|minutes?|hours?|days?|weeks?|months?|years?) (later|earlier)**
+
+  Example:
+  
+        When it is 10 minutes later
+        When it is a few hours earlier
+
+
+
+### web_steps.rb
+
+Most of cucumber-rails' original web steps plus a few of our own. 
+
+Note that cucumber-rails deprecated all its steps quite a while ago with the following
+deprecation notice. Decide for yourself whether you want to use them:
+
+> This file was generated by Cucumber-Rails and is only here to get you a head start
+> These step definitions are thin wrappers around the Capybara/Webrat API that lets you
+> visit pages, interact with widgets and make assertions about page content.
+
+> If you use these step definitions as basis for your features you will quickly end up
+> with features that are:
+
+> * Hard to maintain
+> * Verbose to read
+
+> A much better approach is to write your own higher level step definitions, following
+> the advice in the following blog posts:
+
+> * http://benmabey.com/2008/05/19/imperative-vs-declarative-scenarios-in-user-stories.html
+> * http://dannorth.net/2011/01/31/whose-domain-is-it-anyway/
+> * http://elabs.se/blog/15-you-re-cuking-it-wrong
+
+
+* **When ... within (.*[^:])**
+
+  You can append 'within [selector]' to any other web step
+  Example:
+  
+        Then I should see "some text" within ".page_body"
+
+
+* **Given I am on ...**
+
+  
+
+
+* **When I go to ...**
+
+  
+
+
+* **When I press "..."**
+
+  
+
+
+* **When I follow "..."**
+
+  
+
+
+* **When I fill in "..." with "..."**
+
+  Fill in text field
+
+
+* **When I fill in "..." for "..."**
+
+  Fill in text field
+
+
+* **When I select "..." from "..."**
+
+  Select from select box
+
+
+* **When I check "..."**
+
+  Check a checkbox
+
+
+* **When I uncheck "..."**
+
+  Uncheck a checkbox
+
+
+* **When I choose "..."**
+
+  Select a radio button
+
+
+* **When I attach the file "..." to "..."**
+
+  
+
+
+* **Then I should see "..."**
+
+  Checks that some text appears on the page
+  
+  Note that this does not detect if the text might be hidden via CSS
+
+
+* **Then I should see \/([^\/]*)\/**
+
+  Checks that a regexp appears on the page
+  
+  Note that this does not detect if the text might be hidden via CSS
+
+
+* **Then I should not see "..."**
+
+  
+
+
+* **Then I should not see \/([^\/]*)\/**
+
+  
+
+
+* **Then the "..." field( within ...)? should contain "..."**
+
+  Checks that a input field contains some value
+
+
+* **Then the "..." field( within ...)? should not contain "..."**
+
+  
+
+
+* **Then the "..." field should have the error "..."**
+
+  checks that an input field was wrapped with a validation error
+
+
+* **Then the "..." field should( not)? have an error**
+
+  
+
+
+* **Then the "..." field should have no error**
+
+  
+
+
+* **Then the radio button "..." should( not)? be (checked|selected)**
+
+  
+
+
+* **Then I should be on ...**
+
+  
+
+
+* **Then I should have the following query string:**
+
+  Example:
+  
+        I should have the following query string:
+          | locale        | de  |
+          | currency_code | EUR |
+  
+  Succeeds when the URL contains the given "locale" and "currency_code" params
+
+
+* **Then show me the page**
+
+  Open the current Capybara page using the "launchy" gem
+
+
+* **Then I should( not)? see a field "..."**
+
+  checks for the existance of a input field (given its id or label)
+
+
+* **Then I should( not)? see the (number|amount) ([\-\d,\.]+)( (.*?))?**
+
+  Better way to test for a number of money amount than a `Then I should see`
+  
+  Checks that there is unexpected minus sign, decimal places etc.
+  
+  See [here](https://makandracards.com/makandra/1225-test-that-a-number-or-money-amount-is-shown-with-cucumber) for details
+
+
+* **Then I should get a response with content-type "..."**
+
+  Checks "Content-Type" HTTP header
+
+
+* **Then I should get a download with filename "..."**
+
+  Checks "Content-Disposition" HTTP header
+
+
+* **Then "..." should be selected for "..."**
+
+  Checks that a certain option is selected for a text field
+
+
+* **Then nothing should be selected for "..."?**
+
+  
+
+
+* **Then "..." should( not)? be an option for "..."( within "...")?**
+
+  Checks for the presence of an option in a select
+
+
+* **Then I should see '([^']*)'( within '([^']*)')?**
+
+  Like `Then I should see`, but with single instead of double quotes. In case the string contains quotes as well.
+
+
+* **Then I should see "..." in the HTML**
+
+  Check that the raw HTML contains a string
+
+
+* **Then I should not see "..." in the HTML**
+
+  
+
+
+* **Then I should see an error**
+
+  Checks that status code is 400..599
+
+
+* **When I reload the page**
+
+  
+
+
+* **Then "..." should( not)? be visible**
+
+  Checks that an element is actually visible, also considering styles
+  Within a selenium test, the browser is asked whether the element is really visible
+  In a non-selenium test, we only check for ".hidden", ".invisible" or "style: display:none"
+  
+  More details [here](https://makandracards.com/makandra/1049-capybara-check-that-a-page-element-is-hidden-via-css)
+
+
+* **When I click on "..."**
+
+  Click on some text that might not be a link
+
+
+* **Then I should (not )?see an element "..."**
+
+  Example:
+  
+        Then I should see an element ".page .container"
+
+
+* **Then I should get a text response**
+
+  Checks that the result has content type text/plain
+
+
+* **When I follow "..." inside any "..."**
+
+  Click a link within an element matching the given selector. Will try to be clever
+  and disregard elements that don't contain a matching link.
+  
+  Example:
+  
+        When I follow "Read more" inside any ".text_snippet"
+
+
+
+* **Then I should( not)? see "..." inside any "..."**
+
+  
+
+
+* **When I fill in "..." with "..." inside any "..."**
 
-Most of cucumber-rails' original websteps plus some of our own.
+  
 
-Note that cucumber-rails deprecated those a while ago (you can see the original deprecation notice at the top of [our web_steps](/makandra/spreewald/blob/master/lib/spreewald/web_steps.rb)). Make up your own mind whether you want to use them or not.

data/Rakefile

@@ -1,2 +1,12 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
+
+
+task "update_readme" do
+  require 'support/documentation_generator'
+  readme = File.read('README.md')
+  start_of_steps_section = readme =~ /^## Steps/
+  length_of_steps_section = (readme[(start_of_steps_section+1)..-1] =~ /^##[^#]/) || readme.size - start_of_steps_section
+  readme[start_of_steps_section, length_of_steps_section] = "## Steps\n\n" + DocumentationGenerator::StepDefinitionsDirectory.new('lib/spreewald').format
+  File.open('README.md', 'w') { |f| f.write(readme) }
+end

data/lib/spreewald/development_steps.rb

@@ -1,15 +1,21 @@
+#
+
+# Marks scenario as pending
 Then /^it should work$/ do
   pending
 end
 
+# Starts debugger
 Then /^debugger$/ do
   debugger
 end
 
+# Waits 2 seconds after each step
 AfterStep('@slow-motion') do
   sleep 2
 end
 
+# Waits for keypress after each step
 AfterStep('@single-step') do
   print "Single Stepping. Hit enter to continue"
   STDIN.getc

data/lib/spreewald/email_steps.rb

@@ -4,10 +4,38 @@ Before do
   ActionMailer::Base.deliveries.clear
 end
 
-When /^I clear my emails$/ do
+When /^I clear my e?mails$/ do
   ActionMailer::Base.deliveries.clear
 end
 
+# Example:
+#
+#       Then an email should have been sent with:
+#         """
+#         From: max.mustermann@example.com
+#         To: john.doe@example.com
+#         Subject: Unter anderem der Betreff kann auch "Anführungszeichen" enthalten
+#         Body: ...
+#         Attachments: ...
+#         """
+# 
+# You can skip lines, of course.
+Then /^(an|no) e?mail should have been sent with:$/ do |mode, raw_data|
+  raw_data.strip!
+  conditions = {}.tap do |hash|
+    raw_data.split("\n").each do |row|
+      if row.match(/^[a-z]+: /i)
+        key, value = row.split(": ", 2)
+        hash[key.downcase.to_sym] = value
+      end
+    end
+  end
+  @mail = MailFinder.find(conditions)
+  expectation = mode == 'no' ? 'should_not' : 'should'
+  @mail.send(expectation, be_present)
+end
+
+# nodoc
 Then /^(an|no) e?mail should have been sent((?: |and|with|from "[^"]+"|to "[^"]+"|the subject "[^"]+"|the body "[^"]+"|the attachments "[^"]+")+)$/ do |mode, query|
   conditions = {}
   conditions[:to] = $1 if query =~ /to "([^"]+)"/
@@ -22,6 +50,7 @@ Then /^(an|no) e?mail should have been sent((?: |and|with|from "[^"]+"|to "[^"]+
   @mail.send(expectation, be_present)
 end
 
+# Only works after you have retrieved the mail using "Then an email should have been sent with:"
 When /^I follow the (first|second|third)? ?link in the e?mail$/ do |index_in_words|
   mail = @mail || ActionMailer::Base.deliveries.last
   index = { nil => 0, 'first' => 0, 'second' => 1, 'third' => 2 }[index_in_words]
@@ -32,37 +61,36 @@ Then /^no e?mail should have been sent$/ do
   ActionMailer::Base.deliveries.should be_empty
 end
 
+# Checks that the last sent email includes some text
 Then /^I should see "([^\"]*)" in the e?mail$/ do |text|
   ActionMailer::Base.deliveries.last.body.should include(text)
 end
 
+# Print all sent emails to STDOUT.
 Then /^show me the e?mails$/ do
   ActionMailer::Base.deliveries.each do |mail|
     p [mail.from, mail.to, mail.subject]
   end
 end
 
-Then /^(an|no) e?mail should have been sent with:$/ do |mode, raw_data|
-  raw_data.strip!
-  conditions = {}.tap do |hash|
-    raw_data.split("\n").each do |row|
-      if row.match(/^[a-z]+: /i)
-        key, value = row.split(": ", 2)
-        hash[key.downcase.to_sym] = value
-      end
-    end
-  end
-  @mail = MailFinder.find(conditions)
-  expectation = mode == 'no' ? 'should_not' : 'should'
-  @mail.send(expectation, be_present)
-end
 
+# Only works after you've retrieved the email using "Then an email should have been sent with:"
+#
+# Example:
+#
+#       And that mail should have the following lines in the body:
+#         """
+#         All of these lines
+#         need to be present
+#         """
 Then /^that e?mail should have the following lines in the body:$/ do |body|
   body.each do |line|
     @mail.body.should include(line.strip)
   end
 end
 
+# Only works after you've retrieved the email using "Then an email should have been sent with:"
+# Checks that the text should be included in the retrieved email
 Then /^that e?mail should have the following body:$/ do |body|
   @mail.body.should include(body.strip)
 end

data/lib/spreewald/table_steps.rb

@@ -1,3 +1,8 @@
+# Check the content of tables in your HTML.
+# 
+# See [this article](https://makandracards.com/makandra/763-cucumber-step-to-match-table-rows-with-capybara) for details.
+
+ 
 require 'spreewald_support/tolerance_for_selenium_sync_issues'
 
 module TableStepsHelper

data/lib/spreewald/timecop_steps.rb

@@ -1,13 +1,29 @@
+# Steps to travel through time using [Timecop](https://github.com/jtrupiano/timecop).
+# 
+# See [this article](https://makandracards.com/makandra/1222-useful-cucumber-steps-to-travel-through-time-with-timecop) for details.
+
+
 if defined?(Timecop)
 
+  # Example:
+  #
+  #       Given the date is "2012-02-10"
+  #       Given the time is "2012-02-10 13:40"
   When /^the (?:date|time) is "(\d{4}-\d{2}-\d{2}(?: \d{1,2}:\d{2})?)"$/ do |time|
     Timecop.travel Time.parse(time)
   end
 
+  # Example:
+  #
+  #       Given the time is "13:40"
   When /^the time is "(\d{1,2}:\d{2})"$/ do |time|
     Timecop.travel Time.parse(time) # date will be today
   end
 
+  # Example:
+  #
+  #       When it is 10 minutes later
+  #       When it is a few hours earlier
   When /^it is (\d+|a|some|a few) (seconds?|minutes?|hours?|days?|weeks?|months?|years?) (later|earlier)$/ do |amount, unit, direction|
     amount = case amount
                when 'a'

data/lib/spreewald/web_steps.rb

@@ -1,34 +1,42 @@
-# Deprecation notice from the original web-steps:
+# Most of cucumber-rails' original web steps plus a few of our own. 
 #
-# This file was generated by Cucumber-Rails and is only here to get you a head start
-# These step definitions are thin wrappers around the Capybara/Webrat API that lets you
-# visit pages, interact with widgets and make assertions about page content.
+# Note that cucumber-rails deprecated all its steps quite a while ago with the following
+# deprecation notice. Decide for yourself whether you want to use them:
 #
-# If you use these step definitions as basis for your features you will quickly end up
-# with features that are:
+# > This file was generated by Cucumber-Rails and is only here to get you a head start
+# > These step definitions are thin wrappers around the Capybara/Webrat API that lets you
+# > visit pages, interact with widgets and make assertions about page content.
 #
-# * Hard to maintain
-# * Verbose to read
+# > If you use these step definitions as basis for your features you will quickly end up
+# > with features that are:
 #
-# A much better approach is to write your own higher level step definitions, following
-# the advice in the following blog posts:
+# > * Hard to maintain
+# > * Verbose to read
 #
-# * http://benmabey.com/2008/05/19/imperative-vs-declarative-scenarios-in-user-stories.html
-# * http://dannorth.net/2011/01/31/whose-domain-is-it-anyway/
-# * http://elabs.se/blog/15-you-re-cuking-it-wrong
+# > A much better approach is to write your own higher level step definitions, following
+# > the advice in the following blog posts:
+#
+# > * http://benmabey.com/2008/05/19/imperative-vs-declarative-scenarios-in-user-stories.html
+# > * http://dannorth.net/2011/01/31/whose-domain-is-it-anyway/
+# > * http://elabs.se/blog/15-you-re-cuking-it-wrong
 #
 
 require 'spreewald_support/tolerance_for_selenium_sync_issues'
 require 'spreewald_support/path_selector_fallbacks'
+require 'spreewald_support/step_fallback'
 require 'uri'
 require 'cgi'
 
-# Single-line step scoper
+
+# You can append 'within [selector]' to any other web step
+# Example:
+#
+#       Then I should see "some text" within ".page_body"
 When /^(.*) within (.*[^:])$/ do |nested_step, parent|
   with_scope(parent) { step(nested_step) }
 end
 
-# Multi-line step scoper
+# nodoc
 When /^(.*) within (.*[^:]):$/ do |nested_step, parent, table_or_string|
   with_scope(parent) { step("#{nested_step}:", table_or_string) }
 end
@@ -53,36 +61,42 @@ When /^(?:|I )follow "([^"]*)"$/ do |link|
   end
 end
 
+# Fill in text field
 When /^(?:|I )fill in "([^"]*)" with "([^"]*)"$/ do |field, value|
   patiently do
     fill_in(field, :with => value)
   end
 end
 
+# Fill in text field
 When /^(?:|I )fill in "([^"]*)" for "([^"]*)"$/ do |value, field|
   patiently do
     fill_in(field, :with => value)
   end
 end
 
+# Select from select box
 When /^(?:|I )select "([^"]*)" from "([^"]*)"$/ do |value, field|
   patiently do
     select(value, :from => field)
   end
 end
 
+# Check a checkbox
 When /^(?:|I )check "([^"]*)"$/ do |field|
   patiently do
     check(field)
   end
 end
 
+# Uncheck a checkbox
 When /^(?:|I )uncheck "([^"]*)"$/ do |field|
   patiently do
     uncheck(field)
   end
 end
 
+# Select a radio button
 When /^(?:|I )choose "([^"]*)"$/ do |field|
   patiently do
     choose(field)
@@ -95,12 +109,18 @@ When /^(?:|I )attach the file "([^"]*)" to "([^"]*)"$/ do |path, field|
   end
 end
 
+# Checks that some text appears on the page
+#
+# Note that this does not detect if the text might be hidden via CSS
 Then /^(?:|I )should see "([^"]*)"$/ do |text|
   patiently do
     page.should have_content(text)
   end
 end
 
+# Checks that a regexp appears on the page
+#
+# Note that this does not detect if the text might be hidden via CSS
 Then /^(?:|I )should see \/([^\/]*)\/$/ do |regexp|
   regexp = Regexp.new(regexp)
   patiently do
@@ -121,6 +141,8 @@ Then /^(?:|I )should not see \/([^\/]*)\/$/ do |regexp|
   end
 end
 
+
+# Checks that a input field contains some value
 Then /^the "([^"]*)" field(?: within (.*))? should contain "([^"]*)"$/ do |field, parent, value|
   patiently do
     with_scope(parent) do
@@ -141,6 +163,9 @@ Then /^the "([^"]*)" field(?: within (.*))? should not contain "([^"]*)"$/ do |f
     end
   end
 end
+
+
+# checks that an input field was wrapped with a validation error
 Then /^the "([^"]*)" field should have the error "([^"]*)"$/ do |field, error_message|
   patiently do
     element = find_field(field)
@@ -177,6 +202,7 @@ Then /^the "([^"]*)" field should have no error$/ do |field|
   end
 end
 
+# nodoc
 Then /^the "([^"]*)" checkbox(?: within (.*))? should be checked$/ do |label, parent|
   patiently do
     with_scope(parent) do
@@ -186,6 +212,7 @@ Then /^the "([^"]*)" checkbox(?: within (.*))? should be checked$/ do |label, pa
   end
 end
 
+# nodoc
 Then /^the "([^"]*)" checkbox(?: within (.*))? should not be checked$/ do |label, parent|
   patiently do
     with_scope(parent) do
@@ -208,6 +235,13 @@ Then /^(?:|I )should be on (.+)$/ do |page_name|
   end
 end
 
+# Example:
+#
+#       I should have the following query string:
+#         | locale        | de  |
+#         | currency_code | EUR |
+#
+# Succeeds when the URL contains the given "locale" and "currency_code" params
 Then /^(?:|I )should have the following query string:$/ do |expected_pairs|
   patiently do
     query = URI.parse(current_url).query
@@ -219,11 +253,13 @@ Then /^(?:|I )should have the following query string:$/ do |expected_pairs|
   end
 end
 
+# Open the current Capybara page using the "launchy" gem
 Then /^show me the page$/ do
   save_and_open_page
 end
 
 
+# checks for the existance of a input field (given its id or label)
 Then /^I should( not)? see a field "([^"]*)"$/ do |negate, name|
   expectation = negate ? :should_not : :should
   patiently do
@@ -236,6 +272,11 @@ Then /^I should( not)? see a field "([^"]*)"$/ do |negate, name|
   end
 end
 
+# Better way to test for a number of money amount than a `Then I should see`
+#
+# Checks that there is unexpected minus sign, decimal places etc.
+#
+# See [here](https://makandracards.com/makandra/1225-test-that-a-number-or-money-amount-is-shown-with-cucumber) for details
 Then /^I should( not)? see the (?:number|amount) ([\-\d,\.]+)(?: (.*?))?$/ do |negate, amount, unit|
   no_minus = amount.starts_with?('-') ? '' : '[^\\-]'
   nbsp = 0xC2.chr + 0xA0.chr
@@ -246,20 +287,20 @@ Then /^I should( not)? see the (?:number|amount) ([\-\d,\.]+)(?: (.*?))?$/ do |n
   end
 end
 
+# Checks "Content-Type" HTTP header
 Then /^I should get a response with content-type "([^\"]*)"$/ do |expected_content_type|
   page.response_headers['Content-Type'].should =~ /\A#{Regexp.quote(expected_content_type)}($|;)/
 end
 
+# Checks "Content-Disposition" HTTP header
 Then /^I should get a download with filename "([^\"]*)"$/ do |filename|
   page.response_headers['Content-Disposition'].should =~ /filename="#{filename}"$/
 end
 
-
-Then /^"([^"]*)" should be selected for "([^"]*)"(?: within "([^\"]*)")?$/ do |value, field, selector|
+# Checks that a certain option is selected for a text field
+Then /^"([^"]*)" should be selected for "([^"]*)"$/ do |value, field|
   patiently do
-    with_scope(selector) do
-      field_labeled(field).find(:xpath, ".//option[@selected = 'selected'][text() = '#{value}']").should be_present
-    end
+    field_labeled(field).find(:xpath, ".//option[@selected = 'selected'][text() = '#{value}']").should be_present
   end
 end
 
@@ -270,23 +311,22 @@ Then /^nothing should be selected for "([^"]*)"?$/ do |field|
   end
 end
 
-Then /^"([^"]*)" should( not)? be an option for "([^"]*)"(?: within "([^\"]*)")?$/ do |value, negate, field, selector|
+# Checks for the presence of an option in a select
+Then /^"([^"]*)" should( not)? be an option for "([^"]*)"$/ do |value, negate, field|
   patiently do
-    with_scope(selector) do
-      expectation = negate ? :should_not : :should
-      field_labeled(field).first(:xpath, ".//option[text() = '#{value}']").send(expectation, be_present)
-    end
+    expectation = negate ? :should_not : :should
+    field_labeled(field).find(:xpath, ".//option[text() = '#{value}']").send(expectation, be_present)
   end
 end
 
-Then /^(?:|I )should see '([^']*)'(?: within '([^']*)')?$/ do |text, selector|
+# Like `Then I should see`, but with single instead of double quotes. In case the string contains quotes as well.
+Then /^(?:|I )should see '([^']*)'$/ do |text|
   patiently do
-    with_scope(selector) do
-      page.should have_content(text)
-    end
+    page.should have_content(text)
   end
 end
 
+# Check that the raw HTML contains a string
 Then /^I should see "([^\"]*)" in the HTML$/ do |text|
   patiently do
     page.body.should include(text)
@@ -299,10 +339,12 @@ Then /^I should not see "([^\"]*)" in the HTML$/ do |text|
   end
 end
 
+# Checks that status code is 400..599
 Then /^I should see an error$/ do
   (400 .. 599).should include(page.status_code)
 end
 
+#nodoc
 Then /^the window should be titled "([^"]*)"$/ do |title|
   page.should have_css('title', :text => title)
 end
@@ -311,6 +353,11 @@ When /^I reload the page$/ do
   visit current_path
 end
 
+# Checks that an element is actually visible, also considering styles
+# Within a selenium test, the browser is asked whether the element is really visible
+# In a non-selenium test, we only check for ".hidden", ".invisible" or "style: display:none"
+#
+# More details [here](https://makandracards.com/makandra/1049-capybara-check-that-a-page-element-is-hidden-via-css)
 Then /^"([^\"]+)" should( not)? be visible$/ do |text, negate|
   case Capybara::current_driver
   when :selenium, :webkit
@@ -365,17 +412,21 @@ Then /^"([^\"]+)" should( not)? be visible$/ do |text, negate|
   end
 end
 
+# Click on some text that might not be a link
 When /^I click on "([^\"]+)"$/ do |text|
   matcher = ['*', { :text => text }]
   patiently do
     element = page.find(:css, *matcher)
-    while better_match = element.first(:css, *matcher)
+    while better_match = element.find(:css, *matcher)
       element = better_match
     end
     element.click
   end
 end
 
+# Example:
+#
+#       Then I should see an element ".page .container"
 Then /^I should (not )?see an element "([^"]*)"$/ do |negate, selector|
   expectation = negate ? :should_not : :should
   patiently do
@@ -383,10 +434,18 @@ Then /^I should (not )?see an element "([^"]*)"$/ do |negate, selector|
   end
 end
 
+# Checks that the result has content type text/plain
 Then /^I should get a text response$/ do
   step 'I should get a response with content-type "text/plain"'
 end
 
+# Click a link within an element matching the given selector. Will try to be clever
+# and disregard elements that don't contain a matching link.
+#
+# Example:
+#
+#       When I follow "Read more" inside any ".text_snippet"
+#
 When /^I follow "([^"]*)" inside any "([^"]*)"$/ do |label, selector|
   node = first("#{selector} a", :text => label)
   node.click

data/lib/spreewald_support/step_fallback.rb

@@ -0,0 +1,11 @@
+module StepFallback
+  def step(*args)
+    if defined?(super)
+      super
+    else
+      When(*args)
+    end
+  end
+end
+
+World(StepFallback)

data/lib/spreewald_support/version.rb

@@ -1,3 +1,3 @@
 module Spreewald
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/spreewald.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Spreewald::VERSION
 
-  gem.add_runtime_dependency('cucumber-rails', '>=1.3.0')
+  gem.add_runtime_dependency('cucumber-rails')
   gem.add_runtime_dependency('cucumber')
   gem.add_runtime_dependency('capybara')
 end

data/support/documentation_generator.rb

@@ -0,0 +1,110 @@
+module DocumentationGenerator
+
+  module CommentExtractor
+    def parse_and_format_comment(comment)
+      comment.strip!
+      comment_lines = comment.split("\n").take_while { |line| line =~ /^\s*#/ }
+      comment_lines && comment_lines.join("\n").gsub(/^\s*# ?/, '')
+    end
+  end
+
+  class StepDefinition
+
+    extend CommentExtractor
+
+    def initialize(definition, comment = nil)
+      @definition = definition
+      @comment = comment
+    end
+
+    def self.try_and_parse(code)
+      definition = code[/^\s*((When|Then|Given|AfterStep).*)do/, 1]
+      return unless definition
+      comment = parse_and_format_comment(code)
+      return if comment =~ /\bnodoc\b/
+      new(definition.strip, comment)
+    end
+
+    def format
+      <<-TEXT
+* **#{format_definition}**
+
+#{@comment.gsub(/^/, '  ')}
+      TEXT
+    end
+
+    def format_definition
+      if @definition =~ /AfterStep/
+        @definition[/@\w*/]
+      else
+        @definition.
+          gsub('/^', '').
+          gsub('$/', '').
+          gsub(' ?', ' ').
+          gsub(/\(\[\^\\?"\](\*|\+)\)/, '...').
+          gsub('(?:|I )', 'I ').
+          gsub('?:', '').
+          gsub(/\(\.(\+|\*)\)/, '...')
+      end
+    end
+  end
+
+  class StepDefinitionFile
+
+    include CommentExtractor
+
+    def initialize(filename)
+      @filename = filename
+      @code = File.read(filename)
+      @steps = []
+      extract_comment
+      add_steps
+    end
+
+    def extract_comment
+      @comment = parse_and_format_comment(@code)
+    end
+
+    def add_steps
+      @code.split("\n\n").each do |block|
+        step = StepDefinition.try_and_parse(block)
+        if step
+          @steps << step
+        end
+      end
+    end
+
+    def format
+      <<-TEXT
+### #{format_filename}
+
+#{@comment}
+
+#{format_steps}
+      TEXT
+    end
+
+    def format_filename
+      @filename.split('/').last
+    end
+
+    def format_steps
+      @steps.collect { |step| step.format }.join("\n\n")
+    end
+  end
+
+  class StepDefinitionsDirectory
+    def initialize(directory)
+      @step_definition_files = []
+      Dir["#{directory}/*.rb"].to_a.sort.each do |filename|
+        next if filename =~ /all_steps/
+        @step_definition_files << StepDefinitionFile.new(filename)
+      end
+    end
+
+    def format
+      @step_definition_files.collect { |step_definition_file| step_definition_file.format }.join("\n\n")
+    end
+  end
+
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: spreewald
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 31
   prerelease: 
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Tobias Kraze
@@ -26,12 +26,10 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 27
+        hash: 3
         segments: 
-        - 1
-        - 3
         - 0
-        version: 1.3.0
+        version: "0"
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -89,9 +87,11 @@ files:
 - lib/spreewald_support/github.rb
 - lib/spreewald_support/mail_finder.rb
 - lib/spreewald_support/path_selector_fallbacks.rb
+- lib/spreewald_support/step_fallback.rb
 - lib/spreewald_support/tolerance_for_selenium_sync_issues.rb
 - lib/spreewald_support/version.rb
 - spreewald.gemspec
+- support/documentation_generator.rb
 has_rdoc: true
 homepage: https://github.com/makandra/spreewald
 licenses: []