cuke_iterations 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+pkg/*
+.idea
+features/run.txt
+.DS_Store

data/.travis.yml

@@ -0,0 +1 @@
+rvm: 1.9.2

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+group :development do
+  gem 'rake', '>= 0.9.2'
+  gem 'rspec'
+  gem 'rspec-expectations', :git => "git://github.com/rspec/rspec-expectations.git"
+end
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,36 @@
+GIT
+  remote: git://github.com/rspec/rspec-expectations.git
+  revision: 0b63bf446ce84a613875417121980492571bfa90
+  specs:
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+
+PATH
+  remote: .
+  specs:
+    cuke_iterations (0.0.1)
+      gherkin
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    gherkin (2.4.11)
+      json (>= 1.4.6)
+    json (1.5.3)
+    rake (0.9.2)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-mocks (2.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  cuke_iterations!
+  rake (>= 0.9.2)
+  rspec
+  rspec-expectations!

data/README.md

@@ -0,0 +1,103 @@
+# Cuke Iterations [![Build Status](https://secure.travis-ci.org/jmerrifield/cuke_iterations.png)](http://travis-ci.org/jmerrifield/cuke_iterations)
+
+Multiple invocations of your scenarios, without running Cucumber multiple times.
+
+## Why would I want that?
+
+In order to run different variations of your tests e.g.
+
+* Different browsers/devices (run all my tests in Chrome, Firefox, iPhone simulator etc)
+* Different platforms (run all my tests against a Windows installation, Linux, OS X etc)
+* Some types of multi-tenant scenarios (run all my tests against the Initrode deployment, the Acme deployment etc)
+* Systems which have different, configurable, modes of operation (but behave the same externally) - got a system that can optionally use MySQL, Sqlite or Oracle as the data store?
+
+## Surely there's some way of doing that already?
+
+The only way of 'iterating' over a scenario in Cucumber is to provide it with example rows.  You certainly don't want a table of 'devices' under every single scenario.
+
+## That would suck!  But I can just call Cucumber multiple times from a Rake script!
+
+Absolutely.  It's not without disadvantages though:
+
+* Rake will naturally stop after the first failed command, so you have to code around that fact to have Rake ignore the cucumber failures, and fail at the end if any of the Cucumber runs had failures.
+* No aggregation of results - you have to write your own result aggregation code to get an overall view of how all the variations of your tests did.
+* When your Cucumber suite gets quite large, it can take a significant chunk of time for Cucumber to run your `env.rb` code, and load up all your support and feature files.  That overhead, multiplied by the number of variations, can really add up.
+
+## So how does this gem work?
+
+It's very simple.  Cucumber can accept a file specifying a list of exact scenarios to run, in the format `filename:line_number`.  This is used to re-run failed scenarios, usually in conjunction with the 'rerun' formatter.  This gem takes advantage of that, to send Cucumber a long list of all your scenarios, repeated for each iteration.
+
+## How do I use it?
+
+First, install the gem: `gem install cuke_iterations`
+
+### Configuration - iterations.yml
+
+In your `features` folder, create a YAML file to contain your iterations.  Each one must have a set of included and excluded tags, e.g:
+
+```yaml
+iphone:
+  :include_tags:
+  - ! '@mobile'
+  - ! '@iphone_only'
+  :exclude_tags: []
+android:
+  :include_tags:
+  - ! '@mobile'
+  :exclude_tags:
+  - ! '@iphone_only'
+```
+
+At present, you *must* specify all tags that are to be included.  Excluded tags have priority over included ones (e.g. an `@iphone_only` scenario would not be included in the `android` iteration, even if it had the `@mobile` tag.
+
+### Running it
+
+`cd features`
+
+With defaults:
+`cuke_iterations`
+
+To see other options:
+`cuke_iterations -h`
+
+### What did it do?
+
+First, it created a set of empty directories under the `iterations` folder - one for each iteration that you defined.  You should add this folder to your source-control ignore list (unless you're using Git which doesn't track empty folders).
+
+Next, it created a run file for Cucumber.  If you didn't specify a filename it will be called `run.txt`.  Definitely add this to your source-control ignore list.
+
+### Run Cucumber with the run file instead of a features folder
+
+`cucumber @run.txt`
+
+Note we haven't told Cucumber about our `features` folder like we normally would.  This also means it doesn't know about your `support` or `step_definitions` folders, so make sure to add those to the command-line as well.
+
+### Use the iterations inside your scenarios
+
+In `env.rb`:
+
+```ruby
+require 'cuke_iterations'
+World(CukeIterations::CucumberHelper)
+```
+
+Create a 'Before' hook:
+
+```ruby
+Before do |scenario|
+  iteration = current_iteration(scenario)
+  puts "I'm running under the '#{iteration}' iteration!"
+end
+```
+
+### What should I do now I know which iteration the scenario is running under?
+
+You should `puts` the iteration name to distinguish between instances of the scenario in the Cucumber output.
+
+Depending upon the nature of your iterations, you might like to:
+
+* Switch the browser driver to a device-specific one
+* Change the URL you're running tests against
+* Change the configuration of the system under test
+
+Happy cuking!

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/cuke_iterations

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+require 'cuke_iterations'
+require 'trollop'
+require 'fileutils'
+
+opts = Trollop::options do
+  opt :iteration_file, "Iterations file to use", :default => 'cuke_iterations.yml'
+  opt :out, "Name of runfile to write", :default => 'run.txt'
+end
+
+Trollop::die "Couldn't find iterations file '#{opts[:iteration_file]}'" unless File.exist?(opts[:iteration_file])
+iterations = YAML.load(File.read(opts[:iteration_file]))
+
+all_scenarios = []
+features = CukeIterations::CukeParser.parse_features(Dir.getwd)
+iterations.each do |iteration_name, iteration|
+  iteration_dir = File.join('iterations', iteration_name, '..', '..')
+  FileUtils.mkdir_p iteration_dir
+
+  CukeIterations::ScenarioListGenerator.for_iteration(features, iteration).each do |scenario|
+    all_scenarios << File.join(iteration_dir, scenario[:filename] + ":#{scenario[:line]}")
+  end
+end
+
+File.open(opts[:out], 'w') {|f| f.puts all_scenarios}

data/cuke_iterations.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "cuke_iterations/version"
+
+Gem::Specification.new do |s|
+  s.name        = "cuke_iterations"
+  s.version     = CukeIterations::VERSION
+  s.authors     = ["Jon Merrifield"]
+  s.email       = ["jon@jmerrifield.com"]
+  s.homepage    = "https://github.com/jmerrifield/cuke_iterations"
+  s.summary     = %q{Multiple iterations for Cucumber features}
+  s.description = %q{Run your Cucumber features multiple times within one Cucumber invocation}
+
+  s.rubyforge_project = "cuke_iterations"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.add_dependency 'gherkin'
+end

data/example/features/cuke_iterations.yml

@@ -0,0 +1,10 @@
+iphone:
+  :include_tags:
+  - ! '@tag2'
+  - ! '@tag8'
+  :exclude_tags: []
+android:
+  :include_tags:
+  - ! '@tag2'
+  :exclude_tags:
+  - ! '@tag8'

data/example/features/cuking_rocks.feature

@@ -0,0 +1,22 @@
+@feature_tag1 @feature_tag2
+Feature: My test feature with tags
+  In order to be awesome
+  As a cuker
+  I need to know how many cukes I have, and what colour they are
+
+  Background:
+    Given I have "10" cukes
+
+  Scenario: My scenario
+    When I check my cukes
+    Then I should have "10" cukes
+
+  Scenario Outline: My scenario outline
+    When I check my cukes
+    Then I should have '<cukes>' cukes
+    And I they should be '<colour>' in colour
+
+  Examples:
+    | cukes | colour |
+    | 10    | green  |
+    | 11    | red    |

data/example/features/i_love_cukes.feature

@@ -0,0 +1,25 @@
+Feature: I love cukes
+
+  @tag1 @tag2
+  Scenario: Scenario with tags
+    Given I have "10" cukes
+    When I check my cukes
+    Then I should have "10" cukes
+
+  @tag3 @tag4
+  Scenario Outline: Scenario outline with tags
+    Given I have "<cukes>" cukes
+
+  Examples:
+    | cukes |
+    | 10    |
+    | 11    |
+
+  @tag5 @tag6
+  Scenario Outline: Scenario outline with tags and tagged example sections
+    Given I have "<cukes>" cukes
+
+    @tag7 @tag8
+  Examples:
+    | cukes |
+    | 10    |

data/example/features/support/env.rb

@@ -0,0 +1,3 @@
+require File.dirname(__FILE__) + '/../../../lib/cuke_iterations'
+
+World(CukeIterations::CucumberHelper)

data/example/features/support/hooks.rb

@@ -0,0 +1,4 @@
+Before do |scenario|
+  iteration = current_iteration(scenario)
+  puts "This step is running in the '#{iteration}' iteration!"
+end

data/lib/cuke_iterations/cucumber_helper.rb

@@ -0,0 +1,13 @@
+module CukeIterations
+  module CucumberHelper
+    def current_iteration(scenario)
+      if scenario.is_a? Cucumber::Ast::Scenario
+        scenario.feature.file
+      elsif scenario.is_a? Cucumber::Ast::OutlineTable::ExampleRow
+        scenario.scenario_outline.feature.file
+      else
+        raise "Can't deal with #{scenario.class.name}"
+      end[/iterations\/(.+?)\//, 1]
+    end
+  end
+end

data/lib/cuke_iterations/cuke_parser.rb

@@ -0,0 +1,21 @@
+require 'gherkin'
+
+module CukeIterations
+  class CukeParser
+    class << self
+      def parse_features(dir)
+        scenarios = []
+        Dir.glob(File.join(dir, '**/*.feature')).each do |feature_file|
+          formatter = ScenarioExtractingFormatter.new
+          parser = Gherkin::Parser::Parser.new (formatter)
+          text = File.open(feature_file, 'r') { |f| f.read }
+          parser.parse(text, __FILE__, __LINE__-1)
+
+          scenarios << formatter.discovered_scenarios.each {|s| s[:filename] = File.basename(feature_file)}
+        end
+
+        scenarios.flatten
+      end
+    end
+  end
+end

data/lib/cuke_iterations/scenario_extracting_formatter.rb

@@ -0,0 +1,40 @@
+module CukeIterations
+  class ScenarioExtractingFormatter
+    attr_reader :discovered_scenarios
+
+    def initialize
+      @discovered_scenarios = []
+      @feature_tags = []
+    end
+
+    def feature(feature)
+      @feature_tags = feature.tags.map { |t| t.name }
+    end
+
+    def scenario(scenario)
+      @discovered_scenarios << {
+          line: scenario.line,
+          tags: @feature_tags + scenario.tags.map { |t| t.name }
+      }
+    end
+
+    def scenario_outline(outline)
+      @outline_tags = outline.tags.map { |t| t.name }
+    end
+
+    def examples(examples)
+      examples.rows.each do |row|
+        next if row == examples.rows.first
+
+        @discovered_scenarios << {
+            line: row.line,
+            tags: @feature_tags + @outline_tags + examples.tags.map { |t| t.name }
+        }
+      end
+    end
+
+    def method_missing(sym, *args, &block)
+      # We don't care
+    end
+  end
+end

data/lib/cuke_iterations/scenario_list_generator.rb

@@ -0,0 +1,12 @@
+module CukeIterations
+  class ScenarioListGenerator
+    class << self
+      def for_iteration(parsed_features, iteration)
+        parsed_features.select do |f|
+          next if (f[:tags] & iteration[:exclude_tags]).any?
+          (f[:tags] & iteration[:include_tags]).any?
+        end
+      end
+    end
+  end
+end

data/lib/cuke_iterations/version.rb

@@ -0,0 +1,3 @@
+module CukeIterations
+  VERSION = "0.0.1"
+end

data/lib/cuke_iterations.rb

@@ -0,0 +1,7 @@
+$:.push File.expand_path("../cuke_iterations", __FILE__)
+
+require 'version'
+require 'cuke_parser'
+require 'scenario_extracting_formatter'
+require 'scenario_list_generator'
+require 'cucumber_helper'