gherkin_system 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 932f9e7927f4669a1dccd6af66d25a9f85fa446493d8612a65138558170d569d
-  data.tar.gz: 112171a83d2083bc8a8d1a68412e54dc4e0af3a43afdaaa2c653821df56a1080
+  metadata.gz: 02e33f186f5d635c9b55fce86ad676377685b1e791d6df0e65eb4289660f7f3a
+  data.tar.gz: c4d95982a87a4f4e256549e82fe6b9259881852769967482911f7b92af029691
 SHA512:
-  metadata.gz: a4a601d9c86be652601a73aa4fa5a88b5db61dbff738316983ac8596e9cb7f5abe7c1ecd5d3111e9c6d3e1eeb2010d77f3270926d8ca91a8880ab65ec223d7f4
-  data.tar.gz: b39ecb4ff0463c325bcef5d0bd151d1d0cfc49a7d7d23f22e3f70322b9404cf6d9f074498f6bb6f09c56543fabed0cfe0f3a376587d09e8b83731590f2987bfd
+  metadata.gz: 1618d7d665631a694f721c23047c2d44b94bf3acd0d86ae8f50f9b845cbd0b4941d19ffe300a5d09ba9530d72c97d1e6f43a289a7647dbcef805942c95239e49
+  data.tar.gz: 7d6a37e09d9a91fb390bab01f39b2eef4ad022cac9bca61d27aef9938712f8f9afb79df777a135c89c6935e199747adfd0daa496493ae08671089fec48095001

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-10-04
+
+### Added
+
+- `bin/rails g gherkin_system:install` scaffolds the loader, `features/system/`, and `test/support/gherkin/`
+- `bin/rails g gherkin_system:feature NAME` and `bin/rails g gherkin_system:steps NAME`
+
+### Fixed
+
+- Step assertion failures (`flunk` / `assert`) now wrap in `StepFailure` with feature, step, and line
+- `StepFailure` subclasses `Minitest::Assertion` so Capybara and other step errors report as Failures
+- Failure messages include `bin/rails gherkin path/to.feature:LINE` for rerun
+- Directory paths in `bin/rails gherkin PATH` select features under that directory; unmatched path/line filters raise instead of compiling nothing
+- Nested step generators create the enclosing namespaces, so generated files load without existing modules
+- Step skips remain Minitest skips, and wrapped failures appear in Minitest summary counts
+- Generator tests remove their temporary Ruby files after each test, so test order cannot cause RuboCop failures
+
 ## [0.1.0] - 2026-10-03
 
 ### Initial Release

data/README.md

@@ -13,6 +13,15 @@ Gherkin describes behavior. Rails owns execution. Each scenario becomes a Minite
 gem "gherkin_system"
 ```
 
+```sh
+bundle install
+bin/rails g gherkin_system:install
+bin/rails g gherkin_system:feature checkout
+bin/rails g gherkin_system:steps checkout
+```
+
+`install` creates `test/system/gherkin_test.rb`, `features/system/`, and `test/support/gherkin/`. `feature` and `steps` add a `.feature` file and a steps module; wire the module into the loader with `require_relative` and `config.include_steps`.
+
 ## Agent skill
 
 For agents writing Gherkin scenarios in a Rails app, install the skill with [`npx skills`](https://www.skills.sh/docs/cli):
@@ -25,16 +34,24 @@ Use `-g` for a global install, `-a` to target specific agents, and `-y` to skip
 
 ## Configuration
 
+Configure in the loader created by the install generator:
+
 ```ruby
-# config/initializers/gherkin_system.rb
+# test/system/gherkin_test.rb
+require "application_system_test_case"
+require "gherkin_system/rails"
+
 GherkinSystem.configure do |config|
   config.features = Rails.root.join("features/system/**/*.feature")
-  config.base_test_class = ApplicationSystemTestCase
   config.include_steps AuthenticationSteps
   config.strict = true
 end
+
+GherkinSystem.load!(base: ApplicationSystemTestCase)
 ```
 
+Generated tests subclass the class you pass. The gem does not install its own system-test superclass.
+
 | Option | ENV variable | Default |
 | --- | --- | --- |
 | `features` | | `features/system/**/*.feature` |
@@ -51,18 +68,6 @@ GHERKIN_TAGS="@critical and not @slow" bin/rails test:system
 
 Same filter via the CLI: `bin/rails gherkin --tags "@critical and not @slow"` (sets `GHERKIN_TAGS` for that run). Leave it unset to compile every scenario. If the env var stays set, later `bin/rails test:system` runs keep the filter.
 
-## Rails setup
-
-```ruby
-# test/system/gherkin_test.rb
-require "application_system_test_case"
-require "gherkin_system/rails"
-
-GherkinSystem.load!(base: ApplicationSystemTestCase)
-```
-
-Generated tests subclass the class you pass. The gem does not install its own system-test superclass.
-
 ## Steps
 
 ```ruby
@@ -120,6 +125,7 @@ Rails `setup` runs first. Gherkin hooks and steps run inside the test method. Ra
 
 ```sh
 bin/rails gherkin
+bin/rails gherkin features/system
 bin/rails gherkin features/system/checkout.feature
 bin/rails gherkin features/system/checkout.feature:42
 bin/rails gherkin --tags "@critical and not @slow"
@@ -127,6 +133,8 @@ bin/rails gherkin:check
 bin/rails gherkin:list
 ```
 
+A directory path selects every feature under that directory. A path or line filter that matches nothing raises instead of running an empty suite.
+
 `gherkin:check` parses features and resolves steps. It does not start a browser. `bin/rails test:system` and `bin/rails test:all` run the generated tests as normal Minitest tests.
 
 Tag filters use [Cucumber tag expressions](https://github.com/cucumber/tag-expressions).
@@ -150,7 +158,7 @@ end
 | `UndefinedStep` | No definition matches the step |
 | `AmbiguousStep` | More than one definition matches |
 | `DuplicateStep` | The same pattern is registered twice |
-| `StepFailure` | A step raised. `cause` is the original exception |
+| `StepFailure` | A step raised (`Minitest::Assertion`). `cause` is the original exception. Message includes feature, step, line, and `bin/rails gherkin …` rerun |
 
 Undefined and ambiguous steps raise in `before_setup`, before the driver starts. The message names the feature, scenario, step, feature line, and a suggested definition.
 

data/lib/generators/gherkin_system/feature/feature_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module GherkinSystem
+  module Generators
+    # Creates a Gherkin feature under features/system.
+    class FeatureGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Gherkin feature file under features/system"
+
+      def create_feature
+        template "feature.feature.tt", File.join("features/system", "#{file_path}.feature")
+      end
+    end
+  end
+end

data/lib/generators/gherkin_system/feature/templates/feature.feature.tt

@@ -0,0 +1,3 @@
+Feature: <%= human_name %>
+
+  Scenario: Replace with the condition and result

data/lib/generators/gherkin_system/install/install_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module GherkinSystem
+  module Generators
+    # Scaffolds the loader, feature directory, and steps support directory.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates gherkin_system loader, features/system, and test/support/gherkin"
+
+      def create_loader
+        template "gherkin_test.rb", "test/system/gherkin_test.rb"
+      end
+
+      def create_features_directory
+        empty_directory "features/system"
+        create_file "features/system/.keep", ""
+      end
+
+      def create_steps_directory
+        empty_directory "test/support/gherkin"
+        create_file "test/support/gherkin/.keep", ""
+      end
+    end
+  end
+end

data/lib/generators/gherkin_system/install/templates/gherkin_test.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "application_system_test_case"
+require "gherkin_system/rails"
+
+GherkinSystem.configure do |config|
+  # config.include_steps YourSteps
+end
+
+GherkinSystem.load!(base: ApplicationSystemTestCase)

data/lib/generators/gherkin_system/steps/steps_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module GherkinSystem
+  module Generators
+    # Creates a step definition module under test/support/gherkin.
+    class StepsGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a gherkin_system steps module under test/support/gherkin"
+
+      def create_steps
+        template "steps.rb.tt", File.join("test/support/gherkin", "#{file_path}_steps.rb")
+      end
+
+      def remind_loader_wiring
+        say "Remember to require and include #{steps_module_name} in test/system/gherkin_test.rb", :green
+      end
+
+      private
+
+      def steps_module_name
+        "#{class_name}Steps"
+      end
+    end
+  end
+end

data/lib/generators/gherkin_system/steps/templates/steps.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+<% namespaces = class_name.split("::")[0...-1] -%>
+<% namespaces.each_with_index do |namespace, index| -%>
+<%= "  " * index %>module <%= namespace %>
+<% end -%>
+<%= "  " * namespaces.size %>module <%= class_name.demodulize %>Steps
+<%= "  " * namespaces.size %>  extend GherkinSystem::Steps
+
+<%= "  " * namespaces.size %>  # Given("…") do
+<%= "  " * namespaces.size %>  # end
+<%= "  " * namespaces.size %>end
+<% namespaces.size.times.reverse_each do |index| -%>
+<%= "  " * index %>end
+<% end -%>

data/lib/gherkin_system/errors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "minitest"
+
 module GherkinSystem
   # Base error for gherkin_system failures.
   class Error < StandardError; end
@@ -13,6 +15,46 @@ module GherkinSystem
   # Raised when the same step pattern is registered twice.
   class DuplicateStep < Error; end
 
+  # Formats a bin/rails gherkin rerun hint for a scenario location.
+  module Rerun
+    module_function
+
+    # @param scenario [Scenario]
+    # @param line [Integer, nil]
+    # @return [Array<String>]
+    def footer(scenario, line = scenario.line)
+      ["", "Rerun:", "  bin/rails gherkin #{location(scenario, line)}"]
+    end
+
+    # @param scenario [Scenario]
+    # @param line [Integer, nil]
+    # @return [String]
+    def location(scenario, line = scenario.line)
+      "#{display_path(scenario.uri)}:#{line}"
+    end
+
+    # @param uri [String]
+    # @return [String]
+    def display_path(uri)
+      path = uri.to_s
+      root = project_root
+      return path if root.nil? || root.empty?
+
+      absolute = File.expand_path(path)
+      prefix = "#{File.expand_path(root)}/"
+      return absolute.delete_prefix(prefix) if absolute.start_with?(prefix)
+
+      path
+    end
+
+    # @return [String, nil]
+    def project_root
+      return Rails.root.to_s if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+      Dir.pwd
+    end
+  end
+
   # Raised when no step definition matches.
   class UndefinedStep < Error
     # @param scenario [Scenario]
@@ -27,11 +69,12 @@ module GherkinSystem
         "",
         "  #{step.keyword} #{step.text}",
         "",
-        "#{scenario.uri}:#{step.line}",
+        "#{Rerun.display_path(scenario.uri)}:#{step.line}",
         "",
         "Suggested definition:",
         "",
-        Snippet.for(step)
+        Snippet.for(step),
+        *Rerun.footer(scenario)
       ].join("\n")
     end
   end
@@ -52,16 +95,18 @@ module GherkinSystem
         "",
         "  #{step.keyword} #{step.text}",
         "",
-        "#{scenario.uri}:#{step.line}",
+        "#{Rerun.display_path(scenario.uri)}:#{step.line}",
         "",
         "Matching definitions:",
-        *locations
+        *locations,
+        *Rerun.footer(scenario)
       ].join("\n")
     end
   end
 
   # Wraps a step exception with the feature and definition locations.
-  class StepFailure < Error
+  # Subclasses Minitest::Assertion so wrapped failures report as Failures.
+  class StepFailure < Minitest::Assertion
     # @return [Exception] the original failure
     attr_reader :cause
 
@@ -83,13 +128,24 @@ module GherkinSystem
         "FAILED",
         "",
         "#{step.keyword} #{step.text}",
-        "#{scenario.uri}:#{step.line}",
+        "#{Rerun.display_path(scenario.uri)}:#{step.line}",
         "",
         cause.message.to_s,
         "",
         "Step definition:",
-        definition.location_label
+        definition.location_label,
+        *Rerun.footer(scenario)
       ].join("\n")
     end
   end
+
+  # Minitest counts exact exception classes. Include our assertion subclass.
+  module StepFailureReporting
+    def report
+      super
+      self.failures += results.count { |result| result.failure.is_a?(StepFailure) }
+    end
+  end
 end
+
+Minitest::StatisticsReporter.prepend(GherkinSystem::StepFailureReporting)

data/lib/gherkin_system/executor.rb

@@ -54,7 +54,7 @@ module GherkinSystem
       run_before
       run_steps
       @run.status = :passed
-    rescue StandardError => e
+    rescue Minitest::Assertion, StandardError => e
       @run.status = :failed
       @run.exception = e
       raise
@@ -73,9 +73,9 @@ module GherkinSystem
     def run_step(step)
       definition = registry.resolve(step, @scenario)
       @test.instance_exec(*arguments(definition, step), &definition.block)
-    rescue UndefinedStep, AmbiguousStep
+    rescue UndefinedStep, AmbiguousStep, Minitest::Skip
       raise
-    rescue StandardError => e
+    rescue Minitest::Assertion, StandardError => e
       raise StepFailure.new(@scenario, step, definition, e)
     end
 

data/lib/gherkin_system/feature_loader.rb

@@ -17,7 +17,9 @@ module GherkinSystem
     # @return [Array<Scenario>]
     def scenarios
       selected = files.flat_map { |path| Parser.parse_file(path) }
-      filter_line(filter_path(selected))
+      selected = filter_line(filter_path(selected))
+      ensure_matches!(selected)
+      selected
     end
 
     private
@@ -29,16 +31,14 @@ module GherkinSystem
       paths = Dir.glob(@glob)
       return paths if requested.nil? || requested.empty?
 
-      expanded = File.expand_path(requested)
-      paths.select { |path| File.expand_path(path) == expanded }
+      paths.select { |path| path_match?(path, requested) }
     end
 
     def filter_path(scenarios)
       requested = ENV.fetch("GHERKIN_FEATURES", nil)
       return scenarios if requested.nil? || requested.empty?
 
-      expanded = File.expand_path(requested)
-      scenarios.select { |scenario| File.expand_path(scenario.uri) == expanded }
+      scenarios.select { |scenario| path_match?(scenario.uri, requested) }
     end
 
     def filter_line(scenarios)
@@ -48,5 +48,38 @@ module GherkinSystem
       number = Integer(line)
       scenarios.select { |scenario| scenario.covers_line?(number) }
     end
+
+    def path_match?(path, requested)
+      expanded_path = File.expand_path(path)
+      expanded_requested = File.expand_path(requested)
+      return true if expanded_path == expanded_requested
+
+      return false unless File.directory?(expanded_requested)
+
+      prefix = expanded_requested.end_with?("/") ? expanded_requested : "#{expanded_requested}/"
+      expanded_path.start_with?(prefix)
+    end
+
+    def ensure_matches!(scenarios)
+      return if scenarios.any?
+      return unless filtered?
+
+      raise ConfigurationError, "No scenarios matched #{filter_description}"
+    end
+
+    def filtered?
+      feature = ENV.fetch("GHERKIN_FEATURES", nil)
+      line = ENV.fetch("GHERKIN_LINE", nil)
+      !(feature.nil? || feature.empty?) || !(line.nil? || line.empty?)
+    end
+
+    def filter_description
+      feature = ENV.fetch("GHERKIN_FEATURES", nil)
+      line = ENV.fetch("GHERKIN_LINE", nil)
+      return "#{feature}:#{line}" if feature && line
+      return feature if feature && !feature.empty?
+
+      "line #{line}"
+    end
   end
 end

data/lib/gherkin_system/version.rb

@@ -2,5 +2,5 @@
 
 module GherkinSystem
   # Gem version.
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/rails/commands/gherkin/gherkin_command.rb

@@ -26,6 +26,9 @@ module Rails
       def list(*args)
         prepare!(args)
         scenarios.each { |scenario| puts scenario_line(scenario) }
+      rescue GherkinSystem::Error => e
+        warn e.message
+        exit!(1)
       end
 
       private

data/sig/gherkin_system.rbs

@@ -43,7 +43,7 @@ module GherkinSystem
   class AmbiguousStep < Error
   end
 
-  class StepFailure < Error
+  class StepFailure < ::Minitest::Assertion
     attr_reader cause: Exception
   end
 

data/skills/gherkin-system/SKILL.md

@@ -14,14 +14,19 @@ Do not add cucumber-rails, a Cucumber World, or a second test runner. Do not use
 
 ## Add a scenario
 
-1. Write the feature under `features/system/**/*.feature`.
-2. Bind steps in `test/support/gherkin/*_steps.rb`.
-3. Require that file from `test/system/gherkin_test.rb` before `GherkinSystem.load!`.
-4. Run `bin/rails gherkin:check`.
-5. Run the scenario with `bin/rails gherkin path/to/file.feature:LINE`.
+1. Scaffold with `bin/rails g gherkin_system:feature NAME` and `bin/rails g gherkin_system:steps NAME` (or write the files by hand under `features/system/**/*.feature` and `test/support/gherkin/*_steps.rb`).
+2. Require the steps file from `test/system/gherkin_test.rb` before `GherkinSystem.load!`.
+3. Run `bin/rails gherkin:check`.
+4. Run the scenario with `bin/rails gherkin path/to/file.feature:LINE`.
 
 Create the loader once if it is missing:
 
+```sh
+bin/rails g gherkin_system:install
+```
+
+Then require step modules and register them before `load!`:
+
 ```ruby
 # test/system/gherkin_test.rb
 require "application_system_test_case"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gherkin_system
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - David Paluy
@@ -69,6 +69,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '12'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
 description: gherkin_system turns Gherkin scenarios into Minitest methods on the application's
   ApplicationSystemTestCase. Rails owns execution. Gherkin describes behavior.
 email:
@@ -84,6 +98,12 @@ files:
 - LICENSE
 - LICENSE.txt
 - README.md
+- lib/generators/gherkin_system/feature/feature_generator.rb
+- lib/generators/gherkin_system/feature/templates/feature.feature.tt
+- lib/generators/gherkin_system/install/install_generator.rb
+- lib/generators/gherkin_system/install/templates/gherkin_test.rb
+- lib/generators/gherkin_system/steps/steps_generator.rb
+- lib/generators/gherkin_system/steps/templates/steps.rb.tt
 - lib/gherkin_system.rb
 - lib/gherkin_system/checker.rb
 - lib/gherkin_system/cli.rb
@@ -133,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.20
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Compile Gherkin features into Rails system tests.
 test_files: []