cucumber-core 1.0.0.beta.3 → 1.0.0.beta.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 216ba512564acf2ba3726b04c0c8a59cee4a10fc
-  data.tar.gz: 7ce2adb926a31742c55b1e2956e6e7a4173a00a2
+  metadata.gz: 92d80d8c2127d6475aef16ab947d0bb6123cb65d
+  data.tar.gz: 17c84ce6fef0048f020350837ea4ce963a2983d8
 SHA512:
-  metadata.gz: 9cbfeff310db927f86e1660216fab2960e21020dc926e8279b56b860834b79351c40764f47594309137646cc1267ac115205c6b50b405f7d1528cb592b3a8709
-  data.tar.gz: ad2d596044985b3c7e7679af0933a7a4cc9e92d5f72d3509a9089b516a866bfbf2afc76e9ba1b82c482e7b096c9dde3d1f2661833856bd2bcb8ef507f6707338
+  metadata.gz: 1bd15d9ca8acc459edfe0be347c0de3e4e3a6fc60dbec47f03e3c71824ba71a08dd707c7363a98e55a1d1ea0fea3b43d519a9daf598fc81120061fb28d6d5179
+  data.tar.gz: 3dc08914e80026d9eedc136b4d47f0efda584ebc2094213aebcb06c6886df6cd6091f1da7458b7c6f27e5f706cd1f6f3b628736997c3d6059324ef289f293cc4

data/.yardopts

@@ -0,0 +1,6 @@
+--exclude spec
+--markup markdown
+--no-private
+-
+HISTORY.md
+LICENSE

data/HISTORY.md

@@ -0,0 +1,20 @@
+## [In Git](https://github.com/cucumber/cucumber-ruby-core/compare/v1.0.0.beta.3...master)
+
+### New Features
+
+ * Introduce a Duration object (#[71](https://github.com/cucumber/cucumber-ruby-core/pull/71) [@brasmusson](https://github.com/brasmusson))
+ * BeforeStep hooks (#[70](https://github.com/cucumber/cucumber-ruby-core/pull/70) [@almostwhitehat](https://github.com/almostwhitehat))
+ * Expose `Test::Case#test_steps` (@mattwynne)
+
+### Bugfixes
+
+ * Handle empty feature files (#[77](https://github.com/cucumber/cucumber-ruby-core/pull/77), [cucumber/cucumber#771](https://github.com/cucumber/cucumber/issues/771) [@brasmusson](https://github.com/brasmusson))
+ * Run after hooks in reverse order (#[69](https://github.com/cucumber/cucumber-ruby-core/pull/69) [@erran](https://github.com/erran))
+
+## [v1.0.0.beta.3](https://github.com/cucumber/cucumber-ruby-core/compare/v1.0.0.beta.2...v1.0.0.beta.3)
+
+Changes were not logged.
+
+## [v1.0.0.beta.2](https://github.com/cucumber/cucumber-ruby-core/compare/v1.0.0.beta.1...v1.0.0.beta.2)
+
+Changes were not logged.

data/README.md

@@ -1,9 +1,127 @@
-cucumber-core
-==================
+# cucumber-core
 
 [![Build Status](https://secure.travis-ci.org/cucumber/cucumber-ruby-core.png)](http://travis-ci.org/cucumber/cucumber-ruby-core)
 [![Code Climate](https://codeclimate.com/github/cucumber/cucumber-ruby-core.png)](https://codeclimate.com/github/cucumber/cucumber-ruby-core)
 [![Coverage Status](https://coveralls.io/repos/cucumber/cucumber-ruby-core/badge.png?branch=master)](https://coveralls.io/r/cucumber/cucumber-ruby-core?branch=master)
 [![Dependency Status](https://gemnasium.com/cucumber/cucumber-ruby-core.png)](https://gemnasium.com/cucumber/cucumber-ruby-core)
 
-Core library for the Ruby flavour of Cucumber.
+Cucumber Core is the [inner hexagon](http://alistair.cockburn.us/Hexagonal+architecture) for the [Ruby flavour of Cucumber](https://github.com/cucumber/cucumber).
+
+It contains the core domain logic to execute Cucumber features. It has no user interface, just a Ruby API. If you're interested in how Cucumber works, or in building other tools that work with Gherkin documents, you've come to the right place.
+
+## An overview
+
+The entry-point is a single method on the module `Cucumber::Core` called [`#execute`](http://rubydoc.info/gems/cucumber-core/Cucumber/Core#execute-instance_method). Here's what it does:
+
+1. Parses the plain-text Gherkin documents into an **AST**
+2. Compiles the AST down to **test cases**
+3. Passes the test cases through your **mappings** to activate them
+4. Passes the activated test cases through any **filters**
+5. Executes the test cases, calling back to the **report**
+
+We've introduced a number of concepts here, so let's go through them in detail.
+
+### The AST
+
+The Abstract Syntax Tree or [AST](http://rubydoc.info/gems/cucumber-core/Cucumber/Core/Ast) is an object graph that represents the Gherkin documents you've passed into the core. Things like [Feature](http://rubydoc.info/gems/cucumber-core/Cucumber/Core/Ast/Feature), [Scenario](http://rubydoc.info/gems/cucumber-core/Cucumber/Core/Ast/Scenario) and [ExamplesTable](ExamplesTable).
+
+These are immutable value objects.
+
+### Test cases
+
+Your gherkin might contain scenarios, as well as examples from tables beneath a scenario outline.
+
+Test cases represent the general case of both of these. We compile the AST down to instances of [`Cucumber::Core::Test::Case`](http://rubydoc.info/gems/cucumber-core/Cucumber/Core/Test/Case), each containing a number of instances of [`Cucumber::Core::Test::Step`](http://rubydoc.info/gems/cucumber-core/Cucumber/Core/Test/Step). It's these that are then mapped, filtered, and executed.
+
+Test cases and their test steps are also immutable value objects.
+
+### Mappings
+
+When test cases are first compiled from the AST, they contain no information about how to execute them. Mappings are how we connect them to the code they need to run in order to execute your tests.
+
+### Filters
+
+Once we have the test cases, and they've been activated by the mappings, you may want to pass them through a filter or two. Filters can be used to do things like sort, replace or remove some of the test cases or their steps before they're executed.
+
+In fact, the mappings are just a special case of a filter.
+
+### Report
+
+A report is how you find out what is happening during your test run. As the test cases and steps are executed, messages are sent to the report.
+
+A report needs to respond to the following methods:
+
+* `before_test_case(test_case)`
+* `after_test_case(test_case, result)`
+* `before_test_step(test_step)`
+* `after_test_step(test_test, result)`
+* `done`
+
+That's probably best illustrated with an example.
+
+## Example
+
+Here's an example of how you might use [`Cucumber::Core#execute`](http://rubydoc.info/gems/cucumber-core/Cucumber/Core#execute-instance_method)
+
+```ruby
+require 'cucumber/core'
+
+class MyRunner
+  include Cucumber::Core
+
+  def run(features)
+    execute features, Mappings.new, Report.new
+  end
+
+  class Mappings
+    def test_case(test_case, mapper)
+    end
+
+    def test_step(test_step, mapper)
+      mapper.map { fail } if test_step.name =~ /fail/
+      mapper.map { } if test_step.name =~ /pass/
+    end
+  end
+
+  class Report
+    def before_test_step(test_step)
+    end
+
+    def after_test_step(test_step, result)
+      puts "#{test_step.name} #{result}"
+    end
+
+    def before_test_case(test_case)
+    end
+
+    def after_test_case(test_case, result)
+    end
+
+    def done
+    end
+  end
+
+end
+
+feature = Cucumber::Core::Gherkin::Document.new(__FILE__, <<-GHERKIN)
+Feature:
+  Scenario:
+    Given passing
+    And failing
+    And undefined
+GHERKIN
+
+MyRunner.new.run([feature])
+```
+
+If you run this little Ruby script, you should see the following output:
+
+```
+passing ✓
+failing ✗
+undefined ?
+```
+
+## Copyright
+
+Copyright (c) 2013-2014 Cucumber Limited.

data/cucumber-core.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rake',      '>= 0.9.2'
   s.add_development_dependency 'rspec',     '~> 3'
   s.add_development_dependency 'unindent',  '>= 1.0'
+  s.add_development_dependency 'kramdown',  '~> 1.4.2'
 
   # For coverage reports
   s.add_development_dependency 'coveralls', '~> 0.7'

data/lib/cucumber/core.rb

@@ -1,4 +1,5 @@
 require 'cucumber/core/gherkin/parser'
+require 'cucumber/core/gherkin/document'
 require 'cucumber/core/compiler'
 require 'cucumber/core/test/runner'
 require 'cucumber/core/test/mapper'
@@ -6,6 +7,22 @@ require 'cucumber/core/test/mapper'
 module Cucumber
   module Core
 
+    def execute(gherkin_documents, mapping_definition, report, filters = [])
+      receiver = Test::Runner.new(report)
+      filters << [Test::Mapper, [mapping_definition]]
+      compile gherkin_documents, receiver, filters
+      self
+    end
+
+    def compile(gherkin_documents, last_receiver, filters = [])
+      first_receiver = compose(filters, last_receiver)
+      compiler = Compiler.new(first_receiver)
+      parse gherkin_documents, compiler
+      self
+    end
+
+    private
+
     def parse(gherkin_documents, compiler)
       parser = Core::Gherkin::Parser.new(compiler)
       gherkin_documents.each do |document|
@@ -15,21 +32,10 @@ module Cucumber
       self
     end
 
-    def compile(gherkin_documents, last_receiver, filters = [])
-      first_receiver = filters.reverse.reduce(last_receiver) do |receiver, (filter_type, args)|
+    def compose(filters, last_receiver)
+      filters.reverse.reduce(last_receiver) do |receiver, (filter_type, args)|
         filter_type.new(*args + [receiver])
       end
-      compiler = Compiler.new(first_receiver)
-      parse gherkin_documents, compiler
-      self
-    end
-
-    def execute(gherkin_documents, mapping_definition, report, filters = [], run_options = {})
-      receiver = Test::Runner.new(report)
-      filters << [Test::Mapper, [mapping_definition]]
-      filters << [Test::DebugFilter, []] if run_options[:debug]
-      compile gherkin_documents, receiver, filters
-      self
     end
 
   end

data/lib/cucumber/core/ast/data_table.rb

@@ -100,7 +100,7 @@ module Cucumber
           Hash === array[0] ? hashes_to_array(array) : array
         end
 
-        def hashes_to_array(hashes) #:nodoc:
+        def hashes_to_array(hashes)
           header = hashes[0].keys.sort
           [header] + hashes.map{|hash| header.map{|key| hash[key]}}
         end

data/lib/cucumber/core/ast/examples_table.rb

@@ -40,8 +40,8 @@ module Cucumber
             @cells
           end
 
-          def build_row(row_cells, number, location)
-            Row.new(Hash[@cells.zip(row_cells)], number, location)
+          def build_row(row_cells, number, location, language)
+            Row.new(Hash[@cells.zip(row_cells)], number, location, language)
           end
         end
 
@@ -49,13 +49,14 @@ module Cucumber
           include DescribesItself
           include HasLocation
 
-          attr_reader :number
+          attr_reader :number, :language
 
-          def initialize(data, number, location)
+          def initialize(data, number, location, language)
             raise ArgumentError, data.to_s unless data.is_a?(Hash)
             @data = data
             @number = number
             @location = location
+            @language = language
           end
 
           def ==(other)

data/lib/cucumber/core/ast/feature.rb

@@ -7,7 +7,7 @@ module Cucumber
   module Core
     module Ast
       # Represents the root node of a parsed feature.
-      class Feature #:nodoc:
+      class Feature
         include Names
         include HasLocation
         include DescribesItself
@@ -51,6 +51,12 @@ module Cucumber
         end
 
       end
+
+      class NullFeature
+        def method_missing(*args, &block)
+          self
+        end
+      end
     end
   end
 end

data/lib/cucumber/core/ast/scenario.rb

@@ -7,7 +7,7 @@ require 'cucumber/core/ast/location'
 module Cucumber
   module Core
     module Ast
-      class Scenario #:nodoc:
+      class Scenario
         include Names
         include HasLocation
         include DescribesItself

data/lib/cucumber/core/ast/step.rb

@@ -4,7 +4,7 @@ require 'cucumber/core/ast/location'
 module Cucumber
   module Core
     module Ast
-      class Step #:nodoc:
+      class Step
         include HasLocation
         include DescribesItself
 
@@ -33,7 +33,7 @@ module Cucumber
         end
       end
 
-      class ExpandedOutlineStep < Step #:nodoc:
+      class ExpandedOutlineStep < Step
 
         def initialize(outline_step, gherkin_statement, language, location, keyword, name, multiline_arg)
           @outline_step, @gherkin_statement, @location, @keyword, @name, @multiline_arg = outline_step, gherkin_statement, location, keyword, name, multiline_arg

data/lib/cucumber/core/compiler.rb

@@ -4,6 +4,8 @@ require 'cucumber/core/test/step'
 
 module Cucumber
   module Core
+
+    # Compiles the AST into test cases
     class Compiler
       include Cucumber.initializer(:receiver)
 
@@ -18,6 +20,7 @@ module Cucumber
         self
       end
 
+      # @private
       class TestCaseBuilder
         include Cucumber.initializer(:receiver)
 
@@ -48,6 +51,7 @@ module Cucumber
         end
       end
 
+      # @private
       class FeatureCompiler
         include Cucumber.initializer(:receiver)
 
@@ -80,6 +84,7 @@ module Cucumber
         end
       end
 
+      # @private
       class ScenarioOutlineCompiler
         include Cucumber.initializer(:source, :receiver)
 
@@ -113,6 +118,7 @@ module Cucumber
         end
       end
 
+      # @private
       class ScenarioCompiler
         include Cucumber.initializer(:source, :receiver)
 
@@ -122,6 +128,7 @@ module Cucumber
         end
       end
 
+      # @private
       class BackgroundCompiler
         include Cucumber.initializer(:source, :receiver)
 

data/lib/cucumber/core/gherkin/ast_builder.rb

@@ -12,10 +12,11 @@ module Cucumber
 
         def initialize(path)
           @path = path
+          @feature_builder = nil
         end
 
         def result
-          return nil unless @feature_builder
+          return Ast::NullFeature.new unless @feature_builder
           @feature_builder.result(language)
         end
 
@@ -220,7 +221,7 @@ module Cucumber
 
         class ScenarioOutlineBuilder < Builder
           def result(background, language, feature_tags)
-            raise ParseError.new("Missing Examples section for Scenario Outline at #{location}") if examples_tables.empty?
+            raise ParseError.new("Missing Examples section for Scenario Outline at #{location}") if examples_builders.empty?
             Ast::ScenarioOutline.new(
               node,
               language,
@@ -233,12 +234,12 @@ module Cucumber
               node.name,
               node.description,
               steps(language),
-              examples_tables
+              examples_tables(language)
             )
           end
 
           def add_examples(file, node)
-            examples_tables << ExamplesTableBuilder.new(file, node).result
+            examples_builders << ExamplesTableBuilder.new(file, node)
           end
 
           def add_step(file, node)
@@ -255,13 +256,17 @@ module Cucumber
             @step_builders ||= []
           end
 
-          def examples_tables
-            @examples_tables ||= []
+          def examples_tables(language)
+            examples_builders.map { |examples_builder| examples_builder.result(language) }
+          end
+
+          def examples_builders
+            @examples_builders ||= []
           end
 
           class ExamplesTableBuilder < Builder
 
-            def result
+            def result(language)
               Ast::ExamplesTable.new(
                 node,
                 location,
@@ -271,7 +276,7 @@ module Cucumber
                 node.name,
                 node.description,
                 header,
-                example_rows
+                example_rows(language)
               )
             end
 
@@ -282,10 +287,10 @@ module Cucumber
               Ast::ExamplesTable::Header.new(row.cells, location)
             end
 
-            def example_rows
+            def example_rows(language)
               _, *raw_examples = *node.rows
               raw_examples.each_with_index.map do |row, index|
-                header.build_row(row.cells, index + 1, location.on_line(row.line))
+                header.build_row(row.cells, index + 1, location.on_line(row.line), language)
               end
             end