gherkin_system 0.1.0

data/lib/gherkin_system/hooks.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "cucumber/tag_expressions"
+
+module GherkinSystem
+  # One Before, After, or Around hook.
+  class Hook
+    # @return [Proc]
+    attr_reader :block
+
+    # @param expression [Object, nil] parsed tag expression, or nil to match every scenario
+    # @param block [Proc]
+    def initialize(expression, block)
+      @expression = expression
+      @block = block
+    end
+
+    # @param tags [Array<String>]
+    # @return [Boolean]
+    def applies_to?(tags)
+      @expression.nil? || @expression.evaluate(tags)
+    end
+  end
+
+  # Hooks registered by {Hooks}.
+  class HookRegistry
+    def initialize
+      @hooks = { before: [], after: [], around: [] }
+    end
+
+    # @param kind [Symbol] :before, :after, or :around
+    # @param tag_expression [String, nil]
+    # @param block [Proc]
+    # @return [Hook]
+    def add(kind, tag_expression, block)
+      hook = Hook.new(parse(tag_expression), block)
+      @hooks.fetch(kind) << hook
+      hook
+    end
+
+    # @param kind [Symbol]
+    # @param tags [Array<String>]
+    # @return [Array<Hook>]
+    def matching(kind, tags)
+      @hooks.fetch(kind).select { |hook| hook.applies_to?(tags) }
+    end
+
+    private
+
+    def parse(expression)
+      return nil if expression.nil? || expression.to_s.strip.empty?
+
+      Cucumber::TagExpressions::Parser.new.parse(expression)
+    rescue StandardError => e
+      raise CompilationError, "Malformed hook tag expression #{expression.inspect}: #{e.message}"
+    end
+  end
+
+  # DSL extended by hook modules.
+  #
+  # @example
+  #   module CheckoutHooks
+  #     extend GherkinSystem::Hooks
+  #
+  #     Before("@admin") { visit admin_root_path }
+  #   end
+  module Hooks
+    # @param tag_expression [String, nil]
+    # @return [Hook]
+    def Before(tag_expression = nil, &block)
+      GherkinSystem.hook_registry.add(:before, tag_expression, block)
+    end
+
+    # @param tag_expression [String, nil]
+    # @return [Hook]
+    def After(tag_expression = nil, &block)
+      GherkinSystem.hook_registry.add(:after, tag_expression, block)
+    end
+
+    # @param tag_expression [String, nil]
+    # @return [Hook]
+    def Around(tag_expression = nil, &block)
+      GherkinSystem.hook_registry.add(:around, tag_expression, block)
+    end
+  end
+end

data/lib/gherkin_system/parameter_registry.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "cucumber/cucumber_expressions/parameter_type"
+require "cucumber/cucumber_expressions/parameter_type_registry"
+
+module GherkinSystem
+  # Custom Cucumber Expressions parameter types.
+  class ParameterRegistry
+    # @return [Cucumber::CucumberExpressions::ParameterTypeRegistry]
+    attr_reader :registry
+
+    def initialize
+      @registry = Cucumber::CucumberExpressions::ParameterTypeRegistry.new
+    end
+
+    # @param name [String]
+    # @param regexp [Regexp, String]
+    # @param transformer [Proc]
+    # @param type [Class]
+    # @param prefer_for_regexp_match [Boolean]
+    # @return [void]
+    def define(name:, regexp:, transformer:, type: String, prefer_for_regexp_match: false)
+      parameter = Cucumber::CucumberExpressions::ParameterType.new(
+        name,
+        regexp,
+        type || String,
+        transformer,
+        true,
+        prefer_for_regexp_match
+      )
+      registry.define_parameter_type(parameter)
+    end
+  end
+end

data/lib/gherkin_system/parser.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "gherkin/pickles/compiler"
+require "gherkin/parser"
+
+module GherkinSystem
+  # Turns a feature file into {Scenario} objects. Cucumber messages do not leave this class.
+  class Parser
+    # @param path [String]
+    # @return [Array<Scenario>]
+    def self.parse_file(path)
+      parse(File.read(path), path)
+    end
+
+    # @param source_text [String]
+    # @param uri [String]
+    # @return [Array<Scenario>]
+    def self.parse(source_text, uri)
+      document = Gherkin::Parser.new.parse(source_text)
+      new(document, uri).scenarios
+    rescue Gherkin::ParserError => e
+      raise CompilationError, "#{uri}: #{e.message}"
+    end
+
+    def initialize(document, uri)
+      @document = document
+      @uri = uri.to_s
+      @step_lines = {}
+      @step_keywords = {}
+      @example_rows = {}
+      @scenario_lines = {}
+    end
+
+    # @return [Array<Scenario>]
+    def scenarios
+      return [] unless feature
+
+      index_children(feature.children)
+      pickles.map { |pickle| build_scenario(pickle) }
+    end
+
+    private
+
+    def feature
+      @document.feature
+    end
+
+    def pickles
+      source = Struct.new(:uri).new(@uri)
+      generator = Cucumber::Messages::Helpers::IdGenerator::Incrementing.new
+      Gherkin::Pickles::Compiler.new(generator).compile(@document, source)
+    end
+
+    def index_children(children)
+      children.each do |child|
+        index_children(child.rule.children) if child.rule
+        index_steps(child.background.steps) if child.background
+        index_scenario(child.scenario) if child.scenario
+      end
+    end
+
+    def index_scenario(scenario)
+      @scenario_lines[scenario.id] = scenario.location.line
+      index_steps(scenario.steps)
+      scenario.examples.each do |examples|
+        Array(examples.table_body).each do |row|
+          @example_rows[row.id] = row.cells.map(&:value)
+        end
+      end
+    end
+
+    def index_steps(steps)
+      steps.each do |step|
+        @step_lines[step.id] = step.location.line
+        @step_keywords[step.id] = step.keyword.to_s.strip
+      end
+    end
+
+    def build_scenario(pickle)
+      Scenario.new(
+        uri: @uri,
+        feature_name: feature.name,
+        name: pickle.name,
+        tags: pickle.tags.map(&:name),
+        example_values: example_values(pickle),
+        line: pickle.location.line,
+        scenario_line: scenario_line(pickle),
+        steps: pickle.steps.map { |step| build_step(step) }
+      )
+    end
+
+    def example_values(pickle)
+      pickle.ast_node_ids.filter_map { |id| @example_rows[id] }.first || []
+    end
+
+    def scenario_line(pickle)
+      pickle.ast_node_ids.filter_map { |id| @scenario_lines[id] }.first || pickle.location.line
+    end
+
+    def build_step(pickle_step)
+      step_id = pickle_step.ast_node_ids.first
+      Step.new(
+        text: pickle_step.text,
+        keyword: @step_keywords[step_id] || "Given",
+        line: @step_lines[step_id],
+        table: table_from(pickle_step),
+        doc_string: doc_from(pickle_step)
+      )
+    end
+
+    def table_from(pickle_step)
+      table = pickle_step.argument&.data_table
+      return nil unless table
+
+      DataTable.new(table.rows.map { |row| row.cells.map(&:value) })
+    end
+
+    def doc_from(pickle_step)
+      pickle_step.argument&.doc_string&.content
+    end
+  end
+end

data/lib/gherkin_system/rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "gherkin_system"

data/lib/gherkin_system/railtie.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Loads the gem when Rails boots. Does not replace ApplicationSystemTestCase.
+  class Railtie < Rails::Railtie
+  end
+end

data/lib/gherkin_system/scenario.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # One executable Pickle.
+  Scenario = Data.define(
+    :uri,
+    :feature_name,
+    :name,
+    :tags,
+    :example_values,
+    :line,
+    :scenario_line,
+    :steps
+  ) do
+    # @return [String] Minitest-facing scenario label
+    def test_name
+      label = "#{feature_name}: #{name}"
+      return label if example_values.empty?
+
+      "#{label} [#{example_values.join(", ")}]"
+    end
+
+    # @param number [Integer]
+    # @return [Boolean]
+    def covers_line?(number)
+      lines.include?(number)
+    end
+
+    # @return [Array<Integer>]
+    def lines
+      [line, scenario_line, *steps.map(&:line)].compact.uniq
+    end
+  end
+
+  # One step inside a {Scenario}.
+  Step = Data.define(:text, :keyword, :line, :table, :doc_string)
+end

data/lib/gherkin_system/scenario_run.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Object yielded to hooks. Around hooks continue the scenario with {#run}.
+  class ScenarioRun
+    # @return [String]
+    attr_reader :name
+
+    # @return [String]
+    attr_reader :feature_name
+
+    # @return [Array<String>]
+    attr_reader :tags
+
+    # @return [Exception, nil]
+    attr_accessor :exception
+
+    # @return [Symbol]
+    attr_accessor :status
+
+    # @param scenario [Scenario]
+    def initialize(scenario)
+      @name = scenario.name
+      @feature_name = scenario.feature_name
+      @tags = scenario.tags
+      @status = :pending
+      @exception = nil
+    end
+
+    # Continues the hook chain or the scenario body.
+    #
+    # @return [void]
+    def run
+      @continuation.call
+    end
+
+    # @return [void]
+    def continue_with(&block)
+      @continuation = block
+    end
+  end
+end

data/lib/gherkin_system/snippet.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Builds a step-definition snippet for an undefined step.
+  module Snippet
+    module_function
+
+    # @param step [Step]
+    # @return [String]
+    def for(step)
+      pattern, names = pattern_for(step.text)
+      args = names.empty? ? "" : " |#{names.join(", ")}|"
+      "#{step.keyword}(\"#{pattern}\") do#{args}\n  pending\nend"
+    end
+
+    def pattern_for(text)
+      names = []
+      pattern = text.gsub(/"[^"]*"|'[^']*'/) { names << "string" and "{string}" }
+      pattern = pattern.gsub(/\b\d+\b/) { names << "int" and "{int}" }
+      [pattern, names]
+    end
+  end
+end

data/lib/gherkin_system/step_definition.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "cucumber/cucumber_expressions/cucumber_expression"
+require "cucumber/cucumber_expressions/regular_expression"
+
+module GherkinSystem
+  # One registered Given/When/Then block.
+  class StepDefinition
+    # @return [String, Regexp]
+    attr_reader :pattern
+
+    # @return [Proc]
+    attr_reader :block
+
+    # @return [Array(String, Integer)]
+    attr_reader :location
+
+    # @param pattern [String, Regexp]
+    # @param block [Proc]
+    # @param expression [Object]
+    # @param location [Array(String, Integer)]
+    def initialize(pattern, block, expression, location)
+      @pattern = pattern
+      @block = block
+      @expression = expression
+      @location = location
+    end
+
+    # @param text [String]
+    # @return [Boolean]
+    def matches?(text)
+      !match(text).nil?
+    end
+
+    # @param text [String]
+    # @param test [Object]
+    # @return [Array]
+    def captures(text, test)
+      match(text).map { |argument| argument.value(test) }
+    end
+
+    # @return [String]
+    def location_label
+      "#{location[0]}:#{location[1]}"
+    end
+
+    private
+
+    def match(text)
+      @expression.match(text)
+    end
+  end
+end

data/lib/gherkin_system/step_registry.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Step patterns registered by {Steps}.
+  class StepRegistry
+    def initialize(parameter_registry)
+      @parameter_registry = parameter_registry
+      @definitions = []
+      @keys = {}
+    end
+
+    # @param pattern [String, Regexp]
+    # @param block [Proc]
+    # @return [StepDefinition]
+    def register(pattern, &block)
+      key = pattern.is_a?(Regexp) ? pattern.inspect : pattern.to_s
+      raise DuplicateStep, "Duplicate step definition: #{key}" if @keys.key?(key)
+
+      definition = StepDefinition.new(pattern, block, expression_for(pattern), block.source_location)
+      @keys[key] = definition
+      @definitions << definition
+      definition
+    end
+
+    # @param step [Step]
+    # @param scenario [Scenario]
+    # @return [StepDefinition]
+    def resolve(step, scenario)
+      matches = @definitions.select { |definition| definition.matches?(step.text) }
+      return matches.first if matches.one?
+      raise UndefinedStep.new(scenario, step) if matches.empty?
+
+      raise AmbiguousStep.new(scenario, step, matches)
+    end
+
+    private
+
+    def expression_for(pattern)
+      registry = @parameter_registry.registry
+      if pattern.is_a?(Regexp)
+        Cucumber::CucumberExpressions::RegularExpression.new(pattern, registry)
+      else
+        Cucumber::CucumberExpressions::CucumberExpression.new(pattern.to_s, registry)
+      end
+    end
+  end
+end

data/lib/gherkin_system/steps.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # DSL extended by step-definition modules.
+  #
+  # @example
+  #   module AuthenticationSteps
+  #     extend GherkinSystem::Steps
+  #
+  #     Given("I am signed in") { sign_in users(:customer) }
+  #   end
+  module Steps
+    # @param pattern [String, Regexp]
+    # @return [StepDefinition]
+    def Given(pattern, &)
+      GherkinSystem.step_registry.register(pattern, &)
+    end
+
+    alias When Given
+    alias Then Given
+    alias And Given
+    alias But Given
+
+    # @param name [String]
+    # @param regexp [Regexp, String]
+    # @param type [Class]
+    # @param transformer [Proc]
+    # @return [void]
+    def ParameterType(name:, regexp:, transformer:, type: String, prefer_for_regexp_match: false)
+      GherkinSystem.parameter_registry.define(
+        name: name,
+        regexp: regexp,
+        transformer: transformer,
+        type: type,
+        prefer_for_regexp_match: prefer_for_regexp_match
+      )
+    end
+  end
+end

data/lib/gherkin_system/tag_filter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "cucumber/tag_expressions"
+
+module GherkinSystem
+  # Selects scenarios with a Cucumber tag expression.
+  module TagFilter
+    module_function
+
+    # @param scenarios [Array<Scenario>]
+    # @param expression [String, nil]
+    # @return [Array<Scenario>]
+    def apply(scenarios, expression)
+      return scenarios if expression.nil? || expression.strip.empty?
+
+      parsed = Cucumber::TagExpressions::Parser.new.parse(expression)
+      scenarios.select { |scenario| parsed.evaluate(scenario.tags) }
+    rescue CompilationError
+      raise
+    rescue StandardError => e
+      raise CompilationError, "Invalid tag expression #{expression.inspect}: #{e.message}"
+    end
+  end
+end

data/lib/gherkin_system/test_class_builder.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module GherkinSystem
+  # Namespace for generated test classes.
+  module Suite
+    # Removes generated classes. Used by tests.
+    #
+    # @return [void]
+    def self.reset!
+      constants(false).each { |name| remove_const(name) }
+    end
+  end
+
+  # Defines one Minitest class per feature file.
+  class TestClassBuilder
+    # @param base [Class]
+    def initialize(base)
+      @base = base
+    end
+
+    # @param scenarios [Array<Scenario>]
+    # @return [Array<Class>]
+    def build(scenarios)
+      scenarios.group_by(&:uri).map { |uri, group| build_class(uri, group) }
+    end
+
+    private
+
+    def build_class(uri, scenarios)
+      klass = Class.new(@base)
+      assign_constant(klass, scenarios.first.feature_name, uri)
+      include_step_modules(klass)
+      record_scenarios(klass, define_tests(klass, scenarios))
+      define_preflight(klass)
+      klass
+    end
+
+    def assign_constant(klass, feature_name, uri)
+      name = constant_name(feature_name, uri)
+      Suite.send(:remove_const, name) if Suite.const_defined?(name, false)
+      Suite.const_set(name, klass)
+    end
+
+    def constant_name(feature_name, uri)
+      stem = feature_name.to_s.scan(/[A-Za-z0-9]+/).map(&:capitalize).join
+      stem = "Feature#{stem}" unless stem.match?(/\A[A-Z]/)
+      suffix = Digest::SHA1.hexdigest(uri.to_s)[0, 6]
+      "#{stem}#{suffix}Test"
+    end
+
+    def include_step_modules(klass)
+      GherkinSystem.config.step_modules.each { |mod| klass.include(mod) }
+    end
+
+    def define_tests(klass, scenarios)
+      scenarios.each_with_index.to_h do |scenario, index|
+        method_name = method_name_for(scenario, index)
+        klass.define_method(method_name) { GherkinSystem::Executor.call(self) }
+        [method_name, scenario]
+      end
+    end
+
+    def method_name_for(scenario, index)
+      slug = scenario.test_name.gsub(/[^A-Za-z0-9]+/, "_").gsub(/\A_|_\z/, "")
+      slug = "scenario" if slug.empty?
+      "test_#{slug}_#{index}"
+    end
+
+    def record_scenarios(klass, scenarios_by_method)
+      klass.define_singleton_method(:gherkin_scenarios) { scenarios_by_method }
+    end
+
+    def define_preflight(klass)
+      klass.define_method(:before_setup) do
+        GherkinSystem::Executor.validate!(self) if GherkinSystem.config.strict
+        super() if defined?(super)
+      end
+    end
+  end
+end

data/lib/gherkin_system/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Gem version.
+  VERSION = "0.1.0"
+end

data/lib/gherkin_system.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "gherkin_system/version"
+require_relative "gherkin_system/errors"
+require_relative "gherkin_system/configuration"
+require_relative "gherkin_system/data_table"
+require_relative "gherkin_system/scenario"
+require_relative "gherkin_system/snippet"
+require_relative "gherkin_system/parameter_registry"
+require_relative "gherkin_system/step_definition"
+require_relative "gherkin_system/step_registry"
+require_relative "gherkin_system/steps"
+require_relative "gherkin_system/hooks"
+require_relative "gherkin_system/tag_filter"
+require_relative "gherkin_system/parser"
+require_relative "gherkin_system/feature_loader"
+require_relative "gherkin_system/test_class_builder"
+require_relative "gherkin_system/scenario_run"
+require_relative "gherkin_system/executor"
+require_relative "gherkin_system/checker"
+require_relative "gherkin_system/cli"
+
+# Compiles Gherkin features into Minitest methods on the application's system test class.
+#
+# @example Load features
+#   GherkinSystem.load!(base: ApplicationSystemTestCase)
+module GherkinSystem
+  class << self
+    # @return [Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # @yieldparam config [Configuration]
+    # @return [void]
+    def configure
+      yield(config)
+    end
+
+    # Clears configuration, step definitions, hooks, and generated test classes.
+    #
+    # @return [void]
+    def reset_configuration!
+      @config = nil
+      @step_registry = nil
+      @parameter_registry = nil
+      @hook_registry = nil
+      Suite.reset!
+    end
+
+    # @param glob [String, Pathname, nil]
+    # @param base [Class, nil] system test superclass. Required when config.base_test_class is unset.
+    # @return [Array<Class>] generated test classes
+    def load!(glob = nil, base: nil)
+      test_class = base || config.base_test_class
+      raise ConfigurationError, "Pass base: or set config.base_test_class" if test_class.nil?
+
+      scenarios = TagFilter.apply(FeatureLoader.load(glob), config.tags)
+      TestClassBuilder.new(test_class).build(scenarios)
+    end
+
+    # @return [StepRegistry]
+    def step_registry
+      @step_registry ||= StepRegistry.new(parameter_registry)
+    end
+
+    # @return [ParameterRegistry]
+    def parameter_registry
+      @parameter_registry ||= ParameterRegistry.new
+    end
+
+    # @return [HookRegistry]
+    def hook_registry
+      @hook_registry ||= HookRegistry.new
+    end
+  end
+end
+
+require_relative "gherkin_system/railtie" if defined?(Rails::Railtie)