gherkin_system 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 932f9e7927f4669a1dccd6af66d25a9f85fa446493d8612a65138558170d569d
+  data.tar.gz: 112171a83d2083bc8a8d1a68412e54dc4e0af3a43afdaaa2c653821df56a1080
+SHA512:
+  metadata.gz: a4a601d9c86be652601a73aa4fa5a88b5db61dbff738316983ac8596e9cb7f5abe7c1ecd5d3111e9c6d3e1eeb2010d77f3270926d8ca91a8880ab65ec223d7f4
+  data.tar.gz: b39ecb4ff0463c325bcef5d0bd151d1d0cfc49a7d7d23f22e3f70322b9404cf6d9f074498f6bb6f09c56543fabed0cfe0f3a376587d09e8b83731590f2987bfd

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-03
+
+### Initial Release
+
+- Compile Gherkin features into Minitest methods on the application's system test class
+- Cucumber Expressions, regex step definitions, and custom parameter types
+- Before, After, and Around hooks, tags, data tables, and doc strings
+- `bin/rails gherkin`, `gherkin:check`, and `gherkin:list`

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Paluy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 David Paluy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+# gherkin_system
+
+Compile Gherkin features into Rails system tests.
+
+[![Gem Version](https://badge.fury.io/rb/gherkin_system.svg)](https://badge.fury.io/rb/gherkin_system)
+[![ci](https://github.com/dpaluy/gherkin_system/actions/workflows/ci.yml/badge.svg)](https://github.com/dpaluy/gherkin_system/actions/workflows/ci.yml)
+
+Gherkin describes behavior. Rails owns execution. Each scenario becomes a Minitest method on your `ApplicationSystemTestCase`, so Capybara, fixtures, routes, and screenshots stay the ones you already use. cucumber-rails is a separate runner. This gem is not.
+
+## Installation
+
+```ruby
+gem "gherkin_system"
+```
+
+## Agent skill
+
+For agents writing Gherkin scenarios in a Rails app, install the skill with [`npx skills`](https://www.skills.sh/docs/cli):
+
+```sh
+npx skills add dpaluy/gherkin_system
+```
+
+Use `-g` for a global install, `-a` to target specific agents, and `-y` to skip prompts. The skill source is [`skills/gherkin-system`](skills/gherkin-system/SKILL.md).
+
+## Configuration
+
+```ruby
+# config/initializers/gherkin_system.rb
+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
+```
+
+| Option | ENV variable | Default |
+| --- | --- | --- |
+| `features` | | `features/system/**/*.feature` |
+| `tags` | `GHERKIN_TAGS` | unset → every scenario is compiled |
+| `strict` | | `true`. A broken scenario fails itself. The rest still run |
+| `base_test_class` | | required by `load!` when `base:` is omitted |
+| `test_file` | | `test/system/gherkin_test.rb` |
+
+`config.tags` / `GHERKIN_TAGS` is a [Cucumber tag expression](https://github.com/cucumber/tag-expressions). Only matching scenarios are compiled into Minitest methods:
+
+```sh
+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
+module AuthenticationSteps
+  extend GherkinSystem::Steps
+
+  Given("I am signed in") do
+    sign_in users(:customer)
+  end
+
+  When("I purchase the {string} plan") do |plan|
+    visit plans_path
+    click_on plan
+  end
+
+  Then(/^I have (\d+) products$/) do |count|
+    assert_equal count.to_i, Product.count
+  end
+
+  ParameterType(
+    name: "user",
+    regexp: /alice|bob/,
+    type: User,
+    transformer: ->(name) { users(name.to_sym) }
+  )
+end
+```
+
+`Given`, `When`, `Then`, `And`, and `But` share one registry. Blocks run with `instance_exec` on the system test, so instance variables set in one step are visible in the next.
+
+## Hooks
+
+```ruby
+module CheckoutHooks
+  extend GherkinSystem::Hooks
+
+  Before do
+  end
+
+  Before("@admin") do
+  end
+
+  After do |scenario|
+  end
+
+  Around("@external") do |scenario|
+    scenario.run
+  end
+end
+```
+
+Rails `setup` runs first. Gherkin hooks and steps run inside the test method. Rails `teardown` and failure screenshots run after.
+
+## Commands
+
+```sh
+bin/rails gherkin
+bin/rails gherkin features/system/checkout.feature
+bin/rails gherkin features/system/checkout.feature:42
+bin/rails gherkin --tags "@critical and not @slow"
+bin/rails gherkin:check
+bin/rails gherkin:list
+```
+
+`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).
+
+## Error handling
+
+```ruby
+begin
+  GherkinSystem.load!(base: ApplicationSystemTestCase)
+rescue GherkinSystem::ConfigurationError => e
+  warn e.message
+rescue GherkinSystem::CompilationError => e
+  warn e.message
+end
+```
+
+| Class | When |
+| --- | --- |
+| `ConfigurationError` | Missing base class or test file |
+| `CompilationError` | Invalid Gherkin, tag expression, or hook |
+| `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 |
+
+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.
+
+## Development
+
+```sh
+bin/setup
+bundle exec rake
+bundle exec rake test
+bundle exec rubocop
+```
+
+## Contributing
+
+Issues and pull requests: [github.com/dpaluy/gherkin_system](https://github.com/dpaluy/gherkin_system/issues).
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).
+
+Supported by [Majestic Labs](https://majesticlabs.dev/).

data/lib/gherkin_system/checker.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Static validation. Does not execute steps or start a browser.
+  class Checker
+    # Collected authoring problems.
+    Result = Data.define(:issues) do
+      # @return [Boolean]
+      def ok?
+        issues.empty?
+      end
+
+      # @return [String]
+      def report
+        issues.map(&:message).join("\n\n")
+      end
+    end
+
+    # @param glob [String, Pathname, nil]
+    # @return [Result]
+    def self.call(glob = nil)
+      new(glob).call
+    end
+
+    # @param glob [String, Pathname, nil]
+    def initialize(glob)
+      @glob = glob
+    end
+
+    # @return [Result]
+    def call
+      Result.new(issues)
+    end
+
+    private
+
+    def issues
+      scenarios.flat_map { |scenario| step_issues(scenario) }
+    rescue CompilationError => e
+      [e]
+    end
+
+    def scenarios
+      TagFilter.apply(FeatureLoader.load(@glob), GherkinSystem.config.tags)
+    end
+
+    def step_issues(scenario)
+      scenario.steps.filter_map { |step| step_issue(scenario, step) }
+    end
+
+    def step_issue(scenario, step)
+      GherkinSystem.step_registry.resolve(step, scenario)
+      nil
+    rescue UndefinedStep, AmbiguousStep => e
+      e
+    end
+  end
+end

data/lib/gherkin_system/cli.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Shared argument handling for the Rails commands.
+  module Cli
+    module_function
+
+    # @param args [Array<String>]
+    # @param tags [String, nil]
+    # @return [Array<String>] remaining arguments
+    def apply_filters!(args, tags:)
+      feature = args.shift if args.first && !args.first.start_with?("-")
+      apply_feature!(feature) if feature
+      ENV["GHERKIN_TAGS"] = tags if tags
+      args
+    end
+
+    def apply_feature!(feature)
+      path, line = split_location(feature)
+      ENV["GHERKIN_FEATURES"] = path
+      ENV["GHERKIN_LINE"] = line if line
+    end
+
+    def split_location(feature)
+      match = feature.match(/\A(.+):(\d+)\z/)
+      return [match[1], match[2]] if match
+
+      [feature, nil]
+    end
+
+    # @return [String]
+    def test_file
+      root = defined?(Rails) ? Rails.root : Dir.pwd
+      File.join(root.to_s, GherkinSystem.config.test_file)
+    end
+
+    # @return [void]
+    def prepare_test_env!
+      ENV["RAILS_ENV"] = "test"
+    end
+  end
+end

data/lib/gherkin_system/configuration.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Global settings for feature discovery and generated tests.
+  class Configuration
+    # @return [Array<Module>] modules included into generated test classes
+    attr_reader :step_modules
+
+    # @return [Class, nil] superclass for generated tests
+    # @return [Boolean] when true, undefined steps fail before the driver starts
+    # @return [String] Rails test file that calls {.load!}
+    attr_accessor :base_test_class, :strict, :test_file
+
+    attr_writer :features
+
+    def initialize
+      @step_modules = []
+      @tags_set = false
+      @strict = true
+      @test_file = "test/system/gherkin_test.rb"
+    end
+
+    # @return [String] glob of feature files
+    def features
+      @features ||= default_features
+    end
+
+    # Tag expression used when compiling. Unset values follow ENV["GHERKIN_TAGS"].
+    #
+    # @return [String, nil]
+    def tags
+      return @tags if @tags_set
+
+      ENV.fetch("GHERKIN_TAGS", nil)
+    end
+
+    # @param value [String, nil]
+    # @return [void]
+    def tags=(value)
+      @tags_set = true
+      @tags = value
+    end
+
+    # Include helper methods from a step module into generated test classes.
+    #
+    # @param mod [Module]
+    # @return [void]
+    def include_steps(mod)
+      @step_modules << mod
+    end
+
+    private
+
+    def default_features
+      File.join(root.to_s, "features/system/**/*.feature")
+    end
+
+    def root
+      return Rails.root if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+      Dir.pwd
+    end
+  end
+end

data/lib/gherkin_system/data_table.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Cucumber-compatible data table passed to a step block.
+  class DataTable
+    # @param rows [Array<Array<String>>]
+    def initialize(rows)
+      @rows = rows.map { |row| row.map(&:to_s) }
+    end
+
+    # @return [Array<Array<String>>] every row, including the header
+    def raw
+      @rows
+    end
+
+    # @return [Array<Hash{String => String}>] body rows keyed by the header
+    def hashes
+      header, *body = @rows
+      return [] if header.nil?
+
+      body.map { |row| header.zip(row).to_h }
+    end
+  end
+end

data/lib/gherkin_system/errors.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Base error for gherkin_system failures.
+  class Error < StandardError; end
+
+  # Raised when load configuration is missing or inconsistent.
+  class ConfigurationError < Error; end
+
+  # Raised when a feature, tag expression, or hook cannot be compiled.
+  class CompilationError < Error; end
+
+  # Raised when the same step pattern is registered twice.
+  class DuplicateStep < Error; end
+
+  # Raised when no step definition matches.
+  class UndefinedStep < Error
+    # @param scenario [Scenario]
+    # @param step [Step]
+    def initialize(scenario, step)
+      super(self.class.format(scenario, step))
+    end
+
+    def self.format(scenario, step)
+      [
+        "Undefined step:",
+        "",
+        "  #{step.keyword} #{step.text}",
+        "",
+        "#{scenario.uri}:#{step.line}",
+        "",
+        "Suggested definition:",
+        "",
+        Snippet.for(step)
+      ].join("\n")
+    end
+  end
+
+  # Raised when more than one step definition matches.
+  class AmbiguousStep < Error
+    # @param scenario [Scenario]
+    # @param step [Step]
+    # @param definitions [Array<StepDefinition>]
+    def initialize(scenario, step, definitions)
+      super(self.class.format(scenario, step, definitions))
+    end
+
+    def self.format(scenario, step, definitions)
+      locations = definitions.map { |definition| "  #{definition.location_label}" }
+      [
+        "Ambiguous step:",
+        "",
+        "  #{step.keyword} #{step.text}",
+        "",
+        "#{scenario.uri}:#{step.line}",
+        "",
+        "Matching definitions:",
+        *locations
+      ].join("\n")
+    end
+  end
+
+  # Wraps a step exception with the feature and definition locations.
+  class StepFailure < Error
+    # @return [Exception] the original failure
+    attr_reader :cause
+
+    # @param scenario [Scenario]
+    # @param step [Step]
+    # @param definition [StepDefinition]
+    # @param cause [Exception]
+    def initialize(scenario, step, definition, cause)
+      super(self.class.format(scenario, step, definition, cause))
+      @cause = cause
+      set_backtrace(cause.backtrace)
+    end
+
+    def self.format(scenario, step, definition, cause)
+      [
+        scenario.feature_name,
+        "  #{scenario.name}",
+        "",
+        "FAILED",
+        "",
+        "#{step.keyword} #{step.text}",
+        "#{scenario.uri}:#{step.line}",
+        "",
+        cause.message.to_s,
+        "",
+        "Step definition:",
+        definition.location_label
+      ].join("\n")
+    end
+  end
+end

data/lib/gherkin_system/executor.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Runs one compiled scenario against a test instance.
+  class Executor
+    # @param test [Minitest::Test]
+    # @return [void]
+    def self.validate!(test)
+      new(test).validate!
+    end
+
+    # @param test [Minitest::Test]
+    # @return [void]
+    def self.call(test)
+      new(test).call
+    end
+
+    # @param test [Minitest::Test]
+    def initialize(test)
+      @test = test
+      @scenario = test.class.gherkin_scenarios.fetch(test.name.to_s)
+      @run = ScenarioRun.new(@scenario)
+    end
+
+    # @return [void]
+    def validate!
+      @scenario.steps.each { |step| registry.resolve(step, @scenario) }
+    end
+
+    # @return [void]
+    def call
+      invoke_around(matching(:around)) { run_body }
+    end
+
+    private
+
+    def registry
+      GherkinSystem.step_registry
+    end
+
+    def matching(kind)
+      GherkinSystem.hook_registry.matching(kind, @scenario.tags)
+    end
+
+    def invoke_around(hooks, &body)
+      hook = hooks.first
+      return body.call unless hook
+
+      @run.continue_with { invoke_around(hooks.drop(1), &body) }
+      @test.instance_exec(@run, &hook.block)
+    end
+
+    def run_body
+      run_before
+      run_steps
+      @run.status = :passed
+    rescue StandardError => e
+      @run.status = :failed
+      @run.exception = e
+      raise
+    ensure
+      run_after
+    end
+
+    def run_before
+      matching(:before).each { |hook| @test.instance_exec(@run, &hook.block) }
+    end
+
+    def run_steps
+      @scenario.steps.each { |step| run_step(step) }
+    end
+
+    def run_step(step)
+      definition = registry.resolve(step, @scenario)
+      @test.instance_exec(*arguments(definition, step), &definition.block)
+    rescue UndefinedStep, AmbiguousStep
+      raise
+    rescue StandardError => e
+      raise StepFailure.new(@scenario, step, definition, e)
+    end
+
+    def arguments(definition, step)
+      values = definition.captures(step.text, @test)
+      values << step.table if step.table
+      values << step.doc_string if step.doc_string
+      values
+    end
+
+    def run_after
+      matching(:after).reverse_each { |hook| @test.instance_exec(@run, &hook.block) }
+    rescue StandardError
+      raise unless @run.exception
+    end
+  end
+end

data/lib/gherkin_system/feature_loader.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module GherkinSystem
+  # Discovers feature files and applies path and line filters from the environment.
+  class FeatureLoader
+    # @param glob [String, Pathname, nil]
+    # @return [Array<Scenario>]
+    def self.load(glob = nil)
+      new(glob || GherkinSystem.config.features).scenarios
+    end
+
+    # @param glob [String, Pathname]
+    def initialize(glob)
+      @glob = glob.to_s
+    end
+
+    # @return [Array<Scenario>]
+    def scenarios
+      selected = files.flat_map { |path| Parser.parse_file(path) }
+      filter_line(filter_path(selected))
+    end
+
+    private
+
+    def files
+      requested = ENV.fetch("GHERKIN_FEATURES", nil)
+      return [requested] if requested && File.file?(requested)
+
+      paths = Dir.glob(@glob)
+      return paths if requested.nil? || requested.empty?
+
+      expanded = File.expand_path(requested)
+      paths.select { |path| File.expand_path(path) == expanded }
+    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 }
+    end
+
+    def filter_line(scenarios)
+      line = ENV.fetch("GHERKIN_LINE", nil)
+      return scenarios if line.nil? || line.empty?
+
+      number = Integer(line)
+      scenarios.select { |scenario| scenario.covers_line?(number) }
+    end
+  end
+end