add an initial feature for rerunning failing tests

features/docs/cli/rerun_failing_tests.feature

@@ -0,0 +1,71 @@
+Feature:
+  Rerun gives you a way to get through flaky tests usually pass after a few runs.
+  This gives a development team a way forward other than disabling a valuable test.
+
+  - Specify max rerun count in option
+  - Output information to the screen
+  - Output rerun information in test report
+
+  Questions:
+  use a tag for flaky tests?  Global option to rerun any test that fails?
+
+  Background:
+    Given a flaky step definition
+
+  Scenario: run a flaky test
+    Given a file named "features/fail.feature" with:
+      """
+      Feature: Fails
+
+        Scenario: flaky test
+          Given a flaky step
+
+      """
+    When I run `cucumber features -q`
+    Then it should fail with:
+      """
+      Feature: Fails
+
+        Scenario: flaky test
+          Given a flaky step
+             (RuntimeError)
+            ./features/step_definitions/steps.rb:4:in `flaky_pass'
+            ./features/step_definitions/steps.rb:1:in `/^a flaky step$/'
+            features/fail.feature:4:in `Given a flaky step'
+
+      Failing Scenarios:
+      cucumber features/fail.feature:3
+
+      1 scenario (1 failed)
+      1 step (1 failed)
+
+      """
+  @wip      
+  Scenario: rerun a flaky test
+    Given a file named "features/fail.feature" with:
+      """
+      Feature: Fails
+
+        Scenario: flaky test
+          Given a flaky step
+
+      """
+    When I run `cucumber features --rerun_flakes=1 -q`
+    Then it should pass with:
+      """
+      Feature: Fails
+
+        Scenario: flaky test
+          Given a flaky step
+             (RuntimeError)
+            ./features/step_definitions/steps.rb:4:in `flaky_pass'
+            ./features/step_definitions/steps.rb:1:in `/^a flaky step$/'
+            features/fail.feature:4:in `Given a flaky step'
+
+      Failing Scenarios:
+      cucumber features/fail.feature:3
+
+      1 scenario (1 passed, 1 flake)
+      1 step (1 passed)
+
+      """

features/lib/step_definitions/cucumber_steps.rb

@@ -28,6 +28,19 @@
   STEPS
 end
 
+Given(/^a flaky step definition$/) do
+  write_file 'features/step_definitions/steps.rb',
+
+  <<-STEPS
+  Given(/^a flaky step$/)          { flaky_pass }
+
+  def flaky_pass
+    fail #something here to pass the 2nd time
+  end
+
+  STEPS
+end
+
 Given /^a step definition that looks like this:$/ do |string|
   create_step_definition { string }
 end