cuke_slicer 1.0.0

data/features/tag_logic.feature

@@ -0,0 +1,45 @@
+Feature: Tag logic
+
+  Normally, tag filters are applied using a logical AND. That is, a tag filter will trigger if a
+  test case's tags match ALL of the provided tag filters. If desired, the tag filters can be
+  evaluated using a logical OR and, further, the two kinds of evaluation can be combined.
+
+  Note: All tag filters are 'inclusive' and strings for the purposes of these examples but the same
+  logic notation and limitations apply for exclusive or regular expression tag filters.
+
+
+  Background:
+    And the following feature file "a_test.feature":
+      """
+      Feature:
+
+        @a
+        Scenario: test a
+        @b
+        Scenario: test b
+        @a @b
+        Scenario: test ab
+        @c
+        Scenario: test c
+        @d
+        Scenario: test d
+        @c @d
+        Scenario: test cd
+      """
+
+
+  Scenario Outline: ANDing and ORing tags
+  Tags that are grouped together will be OR'd together before the remaining AND evaluation occurs
+
+    When test cases are extracted from "a_test.feature" using "<tag filters>"
+    Then "<test cases>" are found
+  Examples:
+    | tag filters | test cases                                                                   |
+    | '@a'        | path/to/a_test.feature:4,  path/to/a_test.feature:8                          |
+    | ['@a']      | path/to/a_test.feature:4,  path/to/a_test.feature:8                          |
+    | '@a','@b'   | path/to/a_test.feature:8                                                     |
+    | ['@a','@b'] | path/to/a_test.feature:4, path/to/a_test.feature:6, path/to/a_test.feature:8 |
+
+  Scenario: Complex logic
+    When test cases are extracted from "a_test.feature" using "['@a','@c'],['@b','@d']"
+    Then "path/to/a_test.feature:8, path/to/a_test.feature:14" are found

data/features/test_case_extraction.feature

@@ -0,0 +1,78 @@
+Feature: Test case extraction
+
+  Test cases can be extracted from a source file or directory as a collection of 'file:line' items that
+  can then be conveniently arranged for consumption by some other tool (e.g. Cucumber).
+
+
+  Scenario: Extraction from a file
+    Given the following feature file "a_test.feature":
+      """
+      Feature: A test feature
+
+        Scenario: Test 1
+          * some steps
+
+        Scenario Outline: Test 2
+          * some steps
+        Examples: Block 1
+          | param | value |
+          | a     | 1     |
+          | b     | 2     |
+        Examples: Block 2
+          | param | value |
+          | c     | 3     |
+      """
+    When test cases are extracted from it
+    Then the following test cases are found
+      | path/to/a_test.feature:3  |
+      | path/to/a_test.feature:10 |
+      | path/to/a_test.feature:11 |
+      | path/to/a_test.feature:14 |
+
+  Scenario: Extraction from 'empty' files
+    Given the following feature file "empty.feature":
+      """
+      Feature: Nothing here yet
+      """
+    And the following feature file "really_empty.feature":
+      """
+      """
+    When test cases are extracted from them
+    Then no test cases are found
+
+  Scenario: Extraction from a directory
+    Given the directory "test_directory"
+    And the following feature file "a_test.feature":
+      """
+      Feature: A test feature
+
+        Scenario Outline: Test 1
+          * some steps
+        Examples:
+          | param | value |
+          | a     | 1     |
+          | b     | 2     |
+      """
+    And the directory "test_directory/nested_directory"
+    And the following feature file "another_test.feature":
+      """
+      Feature: Another test feature
+
+        Scenario: Test 2
+          * some steps
+      """
+    When test cases are extracted from "test_directory"
+    Then the following test cases are found
+      | path/to/test_directory/a_test.feature:7                        |
+      | path/to/test_directory/a_test.feature:8                        |
+      | path/to/test_directory/nested_directory/another_test.feature:3 |
+
+  Scenario: Extraction from 'empty' directories
+    Given the directory "test_directory"
+    And the following feature file "empty.feature":
+      """
+      Feature: WIP
+      """
+    And the directory "test_directory/empty_directory"
+    When test cases are extracted from "test_directory"
+    Then no test cases are found

data/features/test_case_filtering.feature

@@ -0,0 +1,130 @@
+Feature: Test case filtering
+
+  The test cases that are extracted by the slicer can be narrowed down by applying various filters
+  that will eliminate results. Exclusive filters will filter out any test case that matches the
+  filter, whereas inclusive filters will filter out non-matching test cases. Filters can be strings,
+  regular expressions, or a custom code block and they can be combined as desired.
+
+
+  Background:
+    Given the directory "test_directory"
+    And the following feature file "a_test.feature":
+      """
+      @feature_tag_1
+      Feature: The first feature
+
+        @test_tag_1
+        Scenario: a scenario
+          * a step
+
+        @test_tag_2
+        Scenario Outline: an outline
+          * a step
+        @example_tag_1
+        Examples: example set 1
+          | param   |
+          | value 1 |
+        @example_tag_2
+        Examples: example set 2
+          | param   |
+          | value 2 |
+      """
+    And the directory "test_directory/nested_directory"
+    And the following feature file "another_test.feature":
+      """
+      @feature_tag_2
+      Feature: The second feature
+
+        @test_tag_3
+        Scenario: another scenario
+          * a step
+      """
+    And the following feature file "a_third_test.feature":
+      """
+      @feature_tag_3
+      Feature: The third feature
+
+        @test_tag_4
+        Scenario Outline: another outline
+          * a step
+        @example_tag_3
+        Examples: example set 3
+          | param   |
+          | value 3 |
+        @example_tag_4
+        Examples: example set 4
+          | param   |
+          | value 4 |
+      """
+
+  Scenario: Filtering by excluded tags
+    When test cases are extracted from "test_directory" using the following exclusive tag filters:
+      | @feature_tag_1 |
+      | /example/      |
+    Then the following test cases are found
+      | path/to/test_directory/a_test.feature:5                         |
+      | path/to/test_directory/nested_directory/another_test.feature:5  |
+      | path/to/test_directory/nested_directory/a_third_test.feature:10 |
+      | path/to/test_directory/nested_directory/a_third_test.feature:14 |
+
+  Scenario: Filtering by included tags
+    When test cases are extracted from "test_directory" using the following inclusive tag filters:
+      | @feature_tag_1 |
+      | /example/      |
+    Then the following test cases are found
+      | path/to/test_directory/a_test.feature:14 |
+      | path/to/test_directory/a_test.feature:18 |
+
+  Scenario: Filter by included path
+    When test cases are extracted from "test_directory" using the following inclusive path filters:
+      | path/to/test_directory/nested_directory/another_test.feature |
+      | /third/                                                      |
+    Then the following test cases are found
+      | path/to/test_directory/nested_directory/another_test.feature:5  |
+      | path/to/test_directory/nested_directory/a_third_test.feature:10 |
+      | path/to/test_directory/nested_directory/a_third_test.feature:14 |
+
+  Scenario: Filter by excluded path
+    When test cases are extracted from "test_directory" using the following exclusive path filters:
+      | path/to/test_directory/nested_directory/another_test.feature |
+      | /third/                                                      |
+    Then the following test cases are found
+      | path/to/test_directory/a_test.feature:5  |
+      | path/to/test_directory/a_test.feature:14 |
+      | path/to/test_directory/a_test.feature:18 |
+
+  Scenario: Custom filtering
+
+  A custom filter will filter out any test case for which the provided code block evaluates to
+  true. There are not separate exclusive and inclusive versions of custom filters since a negation
+  can be included in the code block to achieve the same effect.
+
+    When test cases are extracted from "test_directory" using the following custom filter:
+      """
+      { |test_case|
+        test_case.is_a?(CukeModeler::Scenario) and
+        test_case.get_ancestor(:feature).name =~ /first/
+      }
+      """
+    Then the following test cases are found
+      | path/to/test_directory/a_test.feature:14                        |
+      | path/to/test_directory/a_test.feature:18                        |
+      | path/to/test_directory/nested_directory/another_test.feature:5  |
+      | path/to/test_directory/nested_directory/a_third_test.feature:10 |
+      | path/to/test_directory/nested_directory/a_third_test.feature:14 |
+
+  Scenario: Combining filters
+    Given the following tag filters:
+      | filter type | filter         |
+      | included    | @feature_tag_1 |
+    And the following path filters:
+      | filter type | filter   |
+      | excluded    | /nested/ |
+    And the following custom filter:
+      """
+      { |test_case| test_case.is_a?(CukeModeler::Scenario) }
+      """
+    When test cases are extracted from "test_directory"
+    Then the following test cases are found
+      | path/to/test_directory/a_test.feature:14 |
+      | path/to/test_directory/a_test.feature:18 |

data/features/validation.feature

@@ -0,0 +1,56 @@
+Feature: Validation
+
+  The slicing process will gracefully handle some of the more common problem use cases.
+
+
+  Scenario: Valid filters
+    * The following filter types are valid:
+      | included_tags  |
+      | excluded_tags  |
+      | included_paths |
+      | excluded_paths |
+
+  Scenario: Using an unknown filter type
+    Given a slicer
+    When it tries to extract test cases using an unknown filter type
+    Then an error indicating that the filter type is unknown will be triggered
+
+  Scenario: Using an invalid filter
+
+  Note: Filters can only be strings, regular expressions, or collections thereof.
+
+    Given a slicer
+    When it tries to extract test cases using an invalid filter
+    Then an error indicating that the filter is invalid will be triggered
+
+  Scenario: Trying to slice a non-existent file
+    Given the file "a_test.feature" does not exist
+    When test cases are extracted from it
+    Then an error indicating that the file does not exist will be triggered
+
+  Scenario: Trying to slice a non-existent directory
+    Given the directory "test_directory" does not exist
+    When test cases are extracted from it
+    Then an error indicating that the directory does not exist will be triggered
+
+  Scenario: Trying to slice an invalid feature file
+    And the following feature file:
+      """
+      This does not look like a feature file
+      """
+    When test cases are extracted from it
+    Then an error indicating that the feature file is invalid will be triggered
+
+  Scenario: Non-feature files in sliced directories are ignored
+    Given the directory "test_directory"
+    Given the following feature file "a_test.feature":
+      """
+      Feature: A test feature
+
+        Scenario: Test 1
+          * some steps
+      """
+    And the file "not_a_feature.file"
+    When test cases are extracted from "test_directory"
+    Then the following test cases are found
+      | path/to/test_directory/a_test.feature:3 |

data/lib/cuke_slicer.rb

@@ -0,0 +1,10 @@
+require 'cuke_modeler'
+
+require "cuke_slicer/version"
+require "cuke_slicer/slicer"
+
+
+# Top level module under which the gem code lives.
+module CukeSlicer
+  # Your code goes here...
+end

data/lib/cuke_slicer/slicer.rb

@@ -0,0 +1,249 @@
+module CukeSlicer
+
+  # The object responsible for slicing up a Cucumber test suite into discrete test cases.
+  class Slicer
+
+    # Slices up the given location into individual test cases.
+    #
+    # The location chosen for slicing can be a file or directory path. Optional filters can be provided in order to
+    # ignore certain kinds of test cases. See #known_filters for the available option types. Most options are either a
+    # string or regular expression, although arrays of the same can be given instead if more than one filter is desired.
+    #
+    # A block can be provided as a filter which can allow for maximal filtering flexibility. Note, however, that this
+    # exposes the underlying modeling objects and knowledge of how they work is then required to make good use of the
+    # filter.
+    #
+    # @param target [String] the location that will be sliced up
+    # @param filters [Hash] the filters that will be applied to the sliced test cases
+    def slice(target, filters = {}, &block)
+      validate_target(target)
+      validate_filters(filters)
+
+
+      begin
+        target = File.directory?(target) ? CukeModeler::Directory.new(target) : CukeModeler::FeatureFile.new(target)
+      rescue Gherkin::Lexer::LexingError
+        raise(ArgumentError, "A syntax or lexing problem was encountered while trying to parse #{target}")
+      end
+
+      if target.is_a?(CukeModeler::Directory)
+        sliced_tests = extract_test_cases_from_directory(target, filters, &block)
+      else
+        sliced_tests = extract_test_cases_from_file(target, filters, &block)
+      end
+
+      sliced_tests
+    end
+
+    # The filtering options that are currently supported by the slicer.
+    def self.known_filters
+      [:excluded_tags,
+       :included_tags,
+       :excluded_paths,
+       :included_paths]
+    end
+
+
+    private
+
+
+    def validate_target(target)
+      raise(ArgumentError, "File or directory '#{target}' does not exist") unless File.exists?(target.to_s)
+    end
+
+    def validate_filters(filter_sets)
+      filter_sets.each do |filter_type, filter_value|
+        raise(ArgumentError, "Unknown filter '#{filter_type}'") unless self.class.known_filters.include?(filter_type)
+        raise(ArgumentError, "Invalid filter '#{filter_value}'. Must be a String, Regexp, or Array thereof. Got #{filter_value.class}") unless filter_value.is_a?(String) or filter_value.is_a?(Regexp) or filter_value.is_a?(Array)
+
+        if filter_value.is_a?(Array)
+          validate_tag_collection(filter_value) if filter_type.to_s =~ /tag/
+          validate_path_collection(filter_value) if filter_type.to_s =~ /path/
+        end
+      end
+    end
+
+    def validate_tag_collection(filter_collection)
+      filter_collection.each do |filter|
+        raise(ArgumentError, "Filter '#{filter}' must be a String, Regexp, or Array. Got #{filter.class}") unless filter.is_a?(String) or filter.is_a?(Regexp) or filter.is_a?(Array)
+
+        validate_nested_tag_collection(filter) if filter.is_a?(Array)
+      end
+    end
+
+    def validate_nested_tag_collection(filter_collection)
+      filter_collection.each do |filter|
+        raise(ArgumentError, "Tag filters cannot be nested more than one level deep.") if filter.is_a?(Array)
+        raise(ArgumentError, "Filter '#{filter}' must be a String or Regexp. Got #{filter.class}") unless filter.is_a?(String) or filter.is_a?(Regexp)
+      end
+    end
+
+    def validate_path_collection(filter_collection)
+      filter_collection.each do |filter|
+        raise(ArgumentError, "Filter '#{filter}' must be a String or Regexp. Got #{filter.class}") unless filter.is_a?(String) or filter.is_a?(Regexp)
+      end
+    end
+
+    def extract_test_cases_from_directory(target, filters, &block)
+      entries = Dir.entries(target.path)
+      entries.delete '.'
+      entries.delete '..'
+
+      Array.new.tap do |test_cases|
+        entries.each do |entry|
+          entry = "#{target.path}/#{entry}"
+
+          case
+            when File.directory?(entry)
+              test_cases.concat(extract_test_cases_from_directory(CukeModeler::Directory.new(entry), filters, &block))
+            when entry =~ /\.feature$/
+              test_cases.concat(extract_test_cases_from_file(CukeModeler::FeatureFile.new(entry), filters, &block))
+            else
+              # Non-feature files are ignored
+          end
+        end
+      end
+    end
+
+    def extract_test_cases_from_file(target, filters, &block)
+      Array.new.tap do |test_cases|
+        unless target.feature.nil?
+          tests = target.feature.tests
+
+          runnable_elements = extract_runnable_elements(extract_runnable_block_elements(tests, filters))
+
+          apply_custom_filter(runnable_elements, &block)
+
+          runnable_elements.each do |element|
+            test_cases << "#{element.get_ancestor(:feature_file).path}:#{element.source_line}"
+          end
+        end
+      end
+    end
+
+    def extract_runnable_block_elements(things, filters)
+      Array.new.tap do |elements|
+        things.each do |thing|
+          if thing.is_a?(CukeModeler::Outline)
+            elements.concat(thing.examples)
+          else
+            elements << thing
+          end
+        end
+
+        filter_excluded_paths(elements, filters[:excluded_paths])
+        filter_included_paths(elements, filters[:included_paths])
+        filter_excluded_tags(elements, filters[:excluded_tags])
+        filter_included_tags(elements, filters[:included_tags])
+      end
+    end
+
+    def extract_runnable_elements(things)
+      Array.new.tap do |elements|
+        things.each do |thing|
+          if thing.is_a?(CukeModeler::Example)
+            # Slicing in order to remove the parameter row element
+            elements.concat(thing.row_elements.slice(1, thing.row_elements.count - 1))
+          else
+            elements << thing
+          end
+        end
+      end
+    end
+
+    def apply_custom_filter(elements, &block)
+      if block
+        elements.reject! do |element|
+          block.call(element)
+        end
+      end
+    end
+
+    def filter_excluded_tags(elements, filters)
+      if filters
+        filters = [filters] unless filters.is_a?(Array)
+
+        unless filters.empty?
+          elements.reject! do |element|
+            matching_tag?(element, filters)
+          end
+        end
+      end
+    end
+
+    def filter_included_tags(elements, filters)
+      if filters
+        filters = [filters] unless filters.is_a?(Array)
+
+        elements.keep_if do |element|
+          matching_tag?(element, filters)
+        end
+      end
+    end
+
+    def filter_excluded_paths(elements, filters)
+      if filters
+        filters = [filters] unless filters.is_a?(Array)
+
+        elements.reject! do |element|
+          matching_path?(element, filters)
+        end
+      end
+    end
+
+    def filter_included_paths(elements, filters)
+      if filters
+        filters = [filters] unless filters.is_a?(Array)
+
+        unless filters.empty?
+          elements.keep_if do |element|
+            matching_path?(element, filters)
+          end
+        end
+      end
+    end
+
+    def matching_tag?(element, filters)
+      filters.each do |filter|
+        if filter.is_a?(Array)
+          filter_match = or_filter_match(element, filter)
+        else
+          filter_match = and_filter_match(element, filter)
+        end
+
+        return false unless filter_match
+      end
+
+      true
+    end
+
+    def and_filter_match(element, filter)
+      filter_match(element, filter)
+    end
+
+    def or_filter_match(element, filters)
+      filters.any? do |filter|
+        filter_match(element, filter)
+      end
+    end
+
+    def filter_match(element, filter)
+      if filter.is_a?(Regexp)
+        element.all_tags.any? { |tag| tag =~ filter }
+      else
+        element.all_tags.include?(filter)
+      end
+    end
+
+    def matching_path?(element, filters)
+      filters.any? do |filtered_path|
+        if filtered_path.is_a?(Regexp)
+          element.get_ancestor(:feature_file).path =~ filtered_path
+        else
+          element.get_ancestor(:feature_file).path == filtered_path
+        end
+      end
+    end
+
+  end
+end