gherkin_system 0.1.0

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "rails/command"
+require "gherkin_system"
+
+module Rails
+  module Command
+    # Facade over `bin/rails test`. Subcommands are methods, matching `test:system`.
+    class GherkinCommand < Base
+      class_option :tags, type: :string, desc: "Cucumber tag expression"
+
+      desc "gherkin [PATH]", "Run Gherkin system tests"
+      def perform(*args)
+        prepare!(args)
+        Rails::Command.invoke("test", [GherkinSystem::Cli.test_file, *args])
+      end
+
+      desc "check [PATH]", "Validate Gherkin features without a browser"
+      def check(*args)
+        prepare!(args)
+        load_definitions
+        report(GherkinSystem::Checker.call)
+      end
+
+      desc "list [PATH]", "List compiled Gherkin scenarios"
+      def list(*args)
+        prepare!(args)
+        scenarios.each { |scenario| puts scenario_line(scenario) }
+      end
+
+      private
+
+      def prepare!(args)
+        GherkinSystem::Cli.prepare_test_env!
+        GherkinSystem::Cli.apply_filters!(args, tags: options[:tags])
+        boot_application!
+      end
+
+      def load_definitions
+        test_dir = Rails.root.join("test").to_s
+        $LOAD_PATH.unshift(test_dir) unless $LOAD_PATH.include?(test_dir)
+        path = GherkinSystem::Cli.test_file
+        raise GherkinSystem::ConfigurationError, "Missing #{path}" unless File.exist?(path)
+
+        require path
+      rescue GherkinSystem::Error => e
+        warn e.message
+        exit!(1)
+      end
+
+      def report(result)
+        io = result.ok? ? $stdout : $stderr
+        io.puts(result.ok? ? "Gherkin check passed" : result.report)
+        io.flush
+        exit!(result.ok? ? 0 : 1)
+      end
+
+      def scenarios
+        loaded = GherkinSystem::FeatureLoader.load
+        GherkinSystem::TagFilter.apply(loaded, GherkinSystem.config.tags)
+      end
+
+      def scenario_line(scenario)
+        "#{scenario.uri}:#{scenario.line} #{scenario.test_name}"
+      end
+    end
+  end
+end

data/sig/gherkin_system.rbs

@@ -0,0 +1,64 @@
+module GherkinSystem
+  VERSION: String
+
+  def self.config: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.reset_configuration!: () -> void
+  def self.load!: (?String glob, ?base: Class?) -> Array[Class]
+  def self.step_registry: () -> StepRegistry
+  def self.parameter_registry: () -> ParameterRegistry
+  def self.hook_registry: () -> HookRegistry
+
+  class Configuration
+    attr_reader step_modules: Array[Module]
+    attr_writer features: String
+    attr_writer base_test_class: Class?
+    attr_writer strict: bool
+    attr_writer test_file: String
+
+    def features: () -> String
+    def base_test_class: () -> Class?
+    def strict: () -> bool
+    def test_file: () -> String
+    def tags: () -> String?
+    def tags=: (String?) -> void
+    def include_steps: (Module) -> void
+  end
+
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class CompilationError < Error
+  end
+
+  class DuplicateStep < Error
+  end
+
+  class UndefinedStep < Error
+  end
+
+  class AmbiguousStep < Error
+  end
+
+  class StepFailure < Error
+    attr_reader cause: Exception
+  end
+
+  class DataTable
+    def initialize: (Array[Array[String]]) -> void
+    def raw: () -> Array[Array[String]]
+    def hashes: () -> Array[Hash[String, String]]
+  end
+
+  class Checker
+    def self.call: (?String? glob) -> Result
+
+    class Result
+      def ok?: () -> bool
+      def report: () -> String
+    end
+  end
+end

data/skills/gherkin-system/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: gherkin-system
+description: >-
+  Write and run Rails system tests as Gherkin features with the gherkin_system
+  gem. Use when adding or changing user-facing Rails behavior, acceptance
+  tests, .feature files, step definitions, or bin/rails gherkin commands.
+---
+
+# gherkin_system
+
+Gherkin describes the behavior. Rails runs it. Each scenario becomes a Minitest method on the app's `ApplicationSystemTestCase`.
+
+Do not add cucumber-rails, a Cucumber World, or a second test runner. Do not use this skill to change the gem's own compiler. Gem development follows `AGENTS.md`.
+
+## 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`.
+
+Create the loader once if it is missing:
+
+```ruby
+# test/system/gherkin_test.rb
+require "application_system_test_case"
+require_relative "../support/gherkin/checkout_steps"
+require "gherkin_system/rails"
+
+GherkinSystem.configure do |config|
+  config.include_steps CheckoutSteps
+end
+
+GherkinSystem.load!(base: ApplicationSystemTestCase)
+```
+
+`base:` must be the application's system test class. The generated tests subclass it.
+
+## Write behavior
+
+One scenario proves one outcome. Name it for the condition and the result.
+
+```gherkin
+Feature: Subscription purchase
+
+  Scenario: Customer purchases Pro
+    Given I am signed in
+    When I purchase the "Pro" plan
+    Then my subscription should be active
+```
+
+Use a Scenario Outline only when each row is the same rule with different data. Each row becomes its own test.
+
+Assert the outcome the user was promised. Drive it through the browser and the real application. Do not mock models, controllers, jobs, or mailers to make the scenario pass.
+
+## Bind steps
+
+```ruby
+module CheckoutSteps
+  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("my subscription should be active") do
+    assert_text "Purchase complete"
+    assert_predicate users(:customer).reload.subscription, :active?
+  end
+end
+```
+
+- `Given`, `When`, `Then`, `And`, and `But` share one registry.
+- Blocks run with `instance_exec` on the system test. `visit`, fixtures, routes, assertions, and `@ivars` are that test instance.
+- Call `config.include_steps` when the module also defines helper methods.
+- Prefer Cucumber Expressions (`{string}`, `{int}`). Use a regex only to match an existing definition.
+- Data tables arrive as an object with `#hashes` (string keys) and `#raw`. Doc strings arrive as the content string.
+
+## Hooks
+
+```ruby
+module CheckoutHooks
+  extend GherkinSystem::Hooks
+
+  Before("@admin") do
+  end
+
+  After do |scenario|
+  end
+
+  Around("@external") do |scenario|
+    scenario.run
+  end
+end
+```
+
+Require the hook file before `load!`. Rails `setup` runs before these hooks. Rails `teardown` and failure screenshots run after them. An `Around` hook must call `scenario.run`.
+
+## Commands
+
+| Command | Use |
+| --- | --- |
+| `bin/rails gherkin:check` | Parse and resolve steps. No browser. Run this before executing a scenario. |
+| `bin/rails gherkin PATH:LINE` | Run the scenario at that line. |
+| `bin/rails gherkin --tags "@critical and not @slow"` | Cucumber tag expression. |
+| `bin/rails gherkin:list` | Show compiled scenarios. |
+| `bin/rails test:system` | Run every system test, including compiled scenarios. |
+
+`GHERKIN_TAGS` left set in the environment also filters `bin/rails test:system`. Unset it to compile every scenario.
+
+## When check fails
+
+- Undefined step: add the suggested definition, then re-run check.
+- Ambiguous step: delete or narrow one of the matching definitions.
+- Duplicate pattern: the same string or regex is registered twice.
+- Invalid Gherkin or tag expression: the message includes the feature path.
+
+A missing step fails that scenario before the driver starts. Other scenarios still run.
+
+## Done
+
+`gherkin:check` exits 0, and the scenario exits 0 through `bin/rails gherkin` or `bin/rails test:system`. A check or execution that cannot run is a failure, not a skipped acceptance test.

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: gherkin_system
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Paluy
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cucumber-cucumber-expressions
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '17'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '17'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '21'
+- !ruby/object:Gem::Dependency
+  name: cucumber-gherkin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '28'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '40'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '28'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '40'
+- !ruby/object:Gem::Dependency
+  name: cucumber-tag-expressions
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '12'
+description: gherkin_system turns Gherkin scenarios into Minitest methods on the application's
+  ApplicationSystemTestCase. Rails owns execution. Gherkin describes behavior.
+email:
+- dpaluy@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE
+- LICENSE.txt
+- README.md
+- lib/gherkin_system.rb
+- lib/gherkin_system/checker.rb
+- lib/gherkin_system/cli.rb
+- lib/gherkin_system/configuration.rb
+- lib/gherkin_system/data_table.rb
+- lib/gherkin_system/errors.rb
+- lib/gherkin_system/executor.rb
+- lib/gherkin_system/feature_loader.rb
+- lib/gherkin_system/hooks.rb
+- lib/gherkin_system/parameter_registry.rb
+- lib/gherkin_system/parser.rb
+- lib/gherkin_system/rails.rb
+- lib/gherkin_system/railtie.rb
+- lib/gherkin_system/scenario.rb
+- lib/gherkin_system/scenario_run.rb
+- lib/gherkin_system/snippet.rb
+- lib/gherkin_system/step_definition.rb
+- lib/gherkin_system/step_registry.rb
+- lib/gherkin_system/steps.rb
+- lib/gherkin_system/tag_filter.rb
+- lib/gherkin_system/test_class_builder.rb
+- lib/gherkin_system/version.rb
+- lib/rails/commands/gherkin/gherkin_command.rb
+- sig/gherkin_system.rbs
+- skills/gherkin-system/SKILL.md
+homepage: https://github.com/dpaluy/gherkin_system
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/dpaluy/gherkin_system
+  documentation_uri: https://rubydoc.info/gems/gherkin_system
+  source_code_uri: https://github.com/dpaluy/gherkin_system
+  changelog_uri: https://github.com/dpaluy/gherkin_system/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dpaluy/gherkin_system/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Compile Gherkin features into Rails system tests.
+test_files: []