smartest 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e192221b36307c61da97572a41e866b137f1a668bb9db26bda75fbd6489df89a
-  data.tar.gz: eb3ee1b6ffae15eaf27b88ffbe4d01bfedbb763a7a1d52bb99bae34bd7e8dc97
+  metadata.gz: 6c8e44520f35d8daac5d01122fd2dc2b1f70f0fcbc61c1ff1d2a6c8ce5179a72
+  data.tar.gz: 4400e77b387079fa88978ff82d34b492f250fdf6de75aae773911a5b91672169
 SHA512:
-  metadata.gz: 916737afbb7af9447c571d16de7c08e73ea52686462a2b99c4378a118e38d613fdbe3152f13fbf089fd518b8930c3e8f927451678e58e23777150a3d98158608
-  data.tar.gz: fe618761cbe53ad37bde38182018835b7566d7a205d0edd92c7e43547d002b131771bce65f2f82a66b7dc3afa770c190d3d8ccfd4e374398e0e2341aa22baf98
+  metadata.gz: b5f7dde5de541b2eec20747164936cee3945076fb985c636d4ae2ea2473e0e2b795b9e5b393800b198e2bae5ae8c6e0892ab173d74e995404a1f4941ce27fd57
+  data.tar.gz: 0226224e48d5dfcaa82b9b22fc03ab295cab9fd463f5f0e17bab881d38e9f68eb98946641a45f5b6a13a884d1649c714a6e8aacd86e772b1aa6ec9d82fbf323c

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.6.0
+
+### New Features
+
+- Add Rails browser-test integration with `bundle exec smartest --init-rails`,
+  generated Playwright fixtures, and `Smartest::Rails::TestServer` loaded by
+  explicit `require "smartest/rails"`.
+
+### Breaking Changes
+
+- Make method stubs process-wide across Fibers and Threads. Remove
+  `Smartest::SimpleStub#apply!` and `#reset!`; `#apply` and `#reset` now raise
+  when called on an already-applied or not-applied stub object.
+
 ## 0.5.0
 
 ### Breaking Changes

data/README.md

@@ -141,6 +141,9 @@ To create a Smartest test scaffold:
 For browser tests:
   bundle exec smartest --init-browser
 
+For Rails browser tests:
+  bundle exec smartest --init-rails
+
 See all commands:
   bundle exec smartest --help
 ```
@@ -190,6 +193,7 @@ bundle exec smartest smartest/user_test.rb
 bundle exec smartest smartest/user_test.rb:12
 bundle exec smartest --init
 bundle exec smartest --init-browser
+bundle exec smartest --init-rails
 ```
 
 Output resembles:
@@ -235,6 +239,57 @@ Run the generated browser example with:
 bundle exec smartest smartest/example_browser_test.rb
 ```
 
+## Rails browser quick start
+
+Initialize a Rails browser-test scaffold:
+
+```bash
+bundle exec smartest --init-rails
+```
+
+The Rails init command creates the normal Smartest helper and matcher files,
+then adds:
+
+```text
+smartest/fixtures/rails_system_fixture.rb
+smartest/matchers/playwright_matcher.rb
+smartest/example_rails_system_test.rb
+```
+
+The generated fixture requires `smartest/rails` and starts
+`Smartest::Rails::TestServer` against `Rails.application` in the same Ruby
+process as the test runner. `Smartest::Rails::TestServer` is only loaded by
+explicitly requiring `smartest/rails`; plain `require "smartest"` does not load
+Puma.
+
+This is aimed at local Rails system tests that combine Rails test data, stubs,
+and Playwright browser assertions. It is not a Capybara compatibility layer or
+the main choice for staging / production-like E2E suites; use Node.js
+Playwright Test for that style of E2E testing.
+
+The generated `page` fixture uses a per-test Playwright browser context with
+`baseURL` set to the Rails server URL. Set
+`SMARTEST_RAILS_TEST_SERVER_PORT` when you need a fixed port; otherwise the test
+server asks the OS for an available port.
+
+For Docker sidecar runs, initialize without installing browser binaries into
+the Rails app container:
+
+```bash
+SMARTEST_SKIP_BROWSER_DOWNLOAD=1 bundle exec smartest --init-rails
+```
+
+At runtime, set `PLAYWRIGHT_WS_ENDPOINT`,
+`SMARTEST_RAILS_TEST_SERVER_HOST`, `SMARTEST_RAILS_TEST_SERVER_PORT`, and
+`SMARTEST_RAILS_BASE_URL` so the generated fixture connects to the Playwright
+sidecar and gives the browser a Docker-network URL for Rails.
+
+Run the generated Rails browser example with:
+
+```bash
+bundle exec smartest smartest/example_rails_system_test.rb
+```
+
 ## Defining tests
 
 Use `test` at the top level:
@@ -646,7 +701,7 @@ Use simple stub helpers when a fixture needs to temporarily replace a Ruby
 method and reset it during teardown:
 
 ```ruby
-class PaymentFixture < Smartest::Fixture
+class ApplicationTestFixture < Smartest::Fixture
   fixture :payment_gateway_stub do
     simple_stub_any_instance_of(PaymentGateway, :charge) { :approved }
   end
@@ -657,7 +712,7 @@ Register the fixture class from `around_suite` before tests request the fixture:
 
 ```ruby
 around_suite do |suite|
-  use_fixture PaymentFixture
+  use_fixture ApplicationTestFixture
   suite.run
 end
 ```
@@ -665,10 +720,10 @@ end
 `use_fixture` is available inside `around_suite` or `around_test` blocks, not as
 a top-level method in a test file.
 
-The stub affects existing instances and new instances of the target class in
-the current Fiber until it is reset. Other Fibers and Threads continue to see
-the original method unless they apply their own stub. Tests can request the
-fixture to make the side effect explicit:
+The stub affects existing instances and new instances of the target class until
+it is reset. Method stubs are shared across Fibers and Threads, including a
+Rails test server running in another thread. Tests can request the fixture to
+make the side effect explicit:
 
 ```ruby
 test("checkout succeeds") do |payment_gateway_stub:|
@@ -680,20 +735,22 @@ Use `simple_stub(Time, :now) { fixed_time }` for singleton methods such as class
 methods.
 
 Use `with_stub_const("AppConfig::PAYMENT_PROVIDER", "fake") { ... }` for
-constants in test bodies, `around_test`, or `around_suite`. Constant stubs are
-process-global; avoid concurrent tests that stub the same constant.
+constants in test bodies, `around_test`, or `around_suite`.
+
+Smartest stubs are process-wide state. They are intended for serial test
+execution and for cases like a Rails test server thread serving the current
+test. They do not provide isolation for multi-threaded parallel test execution:
+one test can observe or reset another test's method or constant stub.
 
 The method stub helpers call `Smartest::SimpleStub` internally, apply the stub,
 register `on_teardown { stub.reset }`, and return the stub object.
 `with_stub_const` records the previous constant value, replaces it, yields to
 the block, and restores or removes the constant with `ensure`.
 
-`Smartest::SimpleStub#apply` and `#reset` are idempotent in the current Fiber.
-`apply!` raises
-`Smartest::SimpleStub::AlreadyAppliedError` when the stub is already active in
-the current Fiber, and `reset!` raises
-`Smartest::SimpleStub::NotAppliedError` when it is not active there. See
-[Stubs](documentation/docs/stubs.md).
+`Smartest::SimpleStub#apply` raises
+`Smartest::SimpleStub::AlreadyAppliedError` when the same stub object is already
+applied. `#reset` raises `Smartest::SimpleStub::NotAppliedError` when that stub
+object is not applied. See [Stubs](documentation/docs/stubs.md).
 
 ## Logged-in client example
 

data/SMARTEST_DESIGN.md

@@ -869,6 +869,9 @@ To create a Smartest test scaffold:
 For browser tests:
   bundle exec smartest --init-browser
 
+For Rails browser tests:
+  bundle exec smartest --init-rails
+
 See all commands:
   bundle exec smartest --help
 ```

data/exe/smartest

@@ -28,6 +28,9 @@ usage = <<~USAGE
     bundle exec smartest --init-browser
         Generate a Playwright browser-test scaffold
 
+    bundle exec smartest --init-rails
+        Generate a Rails Playwright browser-test scaffold
+
   Options:
     --profile N
         Print the N slowest tests. Defaults to 5.
@@ -48,6 +51,9 @@ missing_smartest_directory_message = <<~MESSAGE
   For browser tests:
     bundle exec smartest --init-browser
 
+  For Rails browser tests:
+    bundle exec smartest --init-rails
+
   See all commands:
     bundle exec smartest --help
 MESSAGE
@@ -75,6 +81,11 @@ begin
     exit Smartest::InitBrowserGenerator.new.run
   end
 
+  if ARGV.include?("--init-rails")
+    command = :init_rails
+    exit Smartest::InitRailsGenerator.new.run
+  end
+
   Smartest.disable_autorun!
   Smartest.install_dsl!
   test_load_path = File.expand_path("smartest", Dir.pwd)
@@ -103,6 +114,8 @@ rescue Exception => error
       "Error initializing Smartest:"
     when :init_browser
       "Error initializing Smartest browser scaffold:"
+    when :init_rails
+      "Error initializing Smartest Rails browser scaffold:"
     else
       "Error loading tests:"
     end

data/lib/smartest/fixture.rb

@@ -74,7 +74,7 @@ module Smartest
     end
 
     def apply_simple_stub(stub)
-      stub.apply!
+      stub.apply
       on_teardown { stub.reset }
       stub
     end

data/lib/smartest/init_rails_generator.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Smartest
+  class InitRailsGenerator
+    RAILS_SYSTEM_FIXTURE = <<~RUBY
+      # frozen_string_literal: true
+
+      require 'smartest/rails'
+      require "playwright"
+
+      class RailsSystemTestFixture < Smartest::Fixture
+        suite_fixture :rails_server do
+          # Set the environment before loading config/environment so the test
+          # server cannot boot against the development database by default.
+          ENV["RAILS_ENV"] ||= "test"
+          ENV["RACK_ENV"] ||= ENV["RAILS_ENV"]
+          require_relative "../../config/environment"
+
+          server = Smartest::Rails::TestServer.new(
+            app: Rails.application,
+            host: ENV["SMARTEST_RAILS_TEST_SERVER_HOST"],
+            port: ENV["SMARTEST_RAILS_TEST_SERVER_PORT"],
+          )
+          server.start
+          server.wait_for_ready
+
+          on_teardown do
+            server.stop
+            server.wait_for_stopped
+          end
+
+          server
+        end
+
+        suite_fixture :base_url do |rails_server:|
+          ENV.fetch("SMARTEST_RAILS_BASE_URL", rails_server.base_url)
+        end
+
+        suite_fixture :browser do
+          ws_endpoint = ENV["PLAYWRIGHT_WS_ENDPOINT"]
+
+          if ws_endpoint && !ws_endpoint.empty?
+            playwright_execution = Playwright.connect_to_browser_server(
+              ws_endpoint,
+              browser_type: selected_browser_type.to_s,
+            )
+            on_teardown { playwright_execution.stop }
+
+            playwright_execution.browser
+          else
+            playwright_execution = Playwright.create(
+              playwright_cli_executable_path: ENV.fetch(
+                "PLAYWRIGHT_CLI_EXECUTABLE_PATH",
+                "./node_modules/.bin/playwright",
+              )
+            )
+            on_teardown { playwright_execution.stop }
+
+            playwright = playwright_execution.playwright
+            browser = playwright.public_send(selected_browser_type).launch(**browser_launch_options)
+            on_teardown { browser.close }
+            browser
+          end
+        end
+
+        fixture :browser_context do |base_url:, browser:|
+          context = browser.new_context(baseURL: base_url)
+          on_teardown { context.close }
+          context
+        end
+
+        fixture :page do |browser_context:|
+          page = browser_context.new_page
+          on_teardown { page.close }
+          page
+        end
+
+        private
+
+        def selected_browser_type
+          case ENV.fetch("BROWSER", "chromium")
+          when "firefox"
+            :firefox
+          when "webkit"
+            :webkit
+          else
+            :chromium
+          end
+        end
+
+        def browser_launch_options
+          launch_options = {}
+          launch_options[:headless] = !%w[0 false].include?(ENV.fetch("HEADLESS", "true"))
+          if (slow_mo = ENV.fetch("SLOW_MO", "0").to_i) > 0
+            launch_options[:slowMo] = slow_mo
+          end
+
+          launch_options
+        end
+      end
+    RUBY
+
+    PLAYWRIGHT_MATCHER = <<~RUBY
+      # frozen_string_literal: true
+
+      require "playwright"
+      require "playwright/test"
+
+      module PlaywrightMatcher
+        include Playwright::Test::Matchers
+      end
+    RUBY
+
+    EXAMPLE_RAILS_SYSTEM_TEST = <<~RUBY
+      # frozen_string_literal: true
+
+      require "test_helper"
+
+      test("loads the Rails application") do |page:|
+        response = page.goto("/")
+
+        expect(response.status).to be_between(200, 599)
+      end
+    RUBY
+
+    def initialize(root: Dir.pwd, output: $stdout, command_runner: nil)
+      @root = root
+      @output = output
+      @command_runner = command_runner || method(:run_system_command)
+    end
+
+    def run
+      Smartest::InitGenerator.new(
+        root: @root,
+        output: @output,
+        files: smartest_files,
+        final_message: nil
+      ).run
+      create_file("smartest/fixtures/rails_system_fixture.rb", RAILS_SYSTEM_FIXTURE)
+      create_file("smartest/matchers/playwright_matcher.rb", PLAYWRIGHT_MATCHER)
+      update_test_helper
+      update_gemfile
+      install_dependencies
+      @output.puts
+      @output.puts "Run your Rails browser test suite with: bundle exec smartest smartest/example_rails_system_test.rb"
+
+      0
+    end
+
+    private
+
+    def smartest_files
+      Smartest::InitGenerator::FILES.merge("smartest/example_rails_system_test.rb" => EXAMPLE_RAILS_SYSTEM_TEST)
+    end
+
+    def create_file(path, contents)
+      absolute_path = File.join(@root, path)
+
+      if File.exist?(absolute_path)
+        @output.puts "exist   #{path}"
+        return
+      end
+
+      FileUtils.mkdir_p(File.dirname(absolute_path))
+      File.write(absolute_path, contents)
+      @output.puts "create  #{path}"
+    end
+
+    def update_test_helper
+      path = File.join(@root, "smartest/test_helper.rb")
+      contents = File.read(path)
+      updated = ensure_rails_registered(contents)
+
+      return if updated == contents
+
+      File.write(path, updated)
+      @output.puts "update  smartest/test_helper.rb"
+    end
+
+    def ensure_rails_registered(contents)
+      missing_lines = []
+      missing_lines << "  use_fixture RailsSystemTestFixture\n" unless contents.include?("use_fixture RailsSystemTestFixture")
+      missing_lines << "  use_matcher PlaywrightMatcher\n" unless contents.include?("use_matcher PlaywrightMatcher")
+      return contents if missing_lines.empty?
+
+      if contents.include?("use_matcher PredicateMatcher")
+        contents.sub(/^(\s*use_matcher PredicateMatcher\n)/) do
+          "#{Regexp.last_match(1)}#{missing_lines.join}"
+        end
+      else
+        "#{contents.chomp}\n\naround_suite do |suite|\n#{missing_lines.join}  suite.run\nend\n"
+      end
+    end
+
+    def update_gemfile
+      path = File.join(@root, "Gemfile")
+      exists = File.exist?(path)
+      contents = exists ? File.read(path) : "source \"https://rubygems.org\"\n"
+
+      if contents.match?(/gem ["']playwright-ruby-client["']/)
+        @output.puts "exist   Gemfile playwright-ruby-client"
+        return
+      end
+
+      separator = contents.end_with?("\n") ? "" : "\n"
+      updated = "#{contents}#{separator}\ngem \"playwright-ruby-client\", group: :test\n"
+      File.write(path, updated)
+      @output.puts(exists ? "update  Gemfile" : "create  Gemfile")
+    end
+
+    def install_dependencies
+      install_commands.each do |command|
+        @output.puts "run     #{command.join(" ")}"
+        next if @command_runner.call(command, chdir: @root)
+
+        raise "command failed: #{command.join(" ")}"
+      end
+
+      if skip_browser_download?
+        @output.puts "skip    ./node_modules/.bin/playwright install (SMARTEST_SKIP_BROWSER_DOWNLOAD=1)"
+      end
+    end
+
+    def install_commands
+      commands = [["bundle", "install"]]
+      commands << ["npm", "init", "--yes"] unless File.exist?(File.join(@root, "package.json"))
+      commands << ["npm", "install", "playwright", "--save-dev"]
+      commands << ["./node_modules/.bin/playwright", "install"] unless skip_browser_download?
+      commands
+    end
+
+    def skip_browser_download?
+      %w[1 true].include?(ENV.fetch("SMARTEST_SKIP_BROWSER_DOWNLOAD", "false"))
+    end
+
+    def run_system_command(command, chdir:)
+      system(*command, chdir: chdir)
+    end
+  end
+end

data/lib/smartest/rails.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "puma"
+require "timeout"
+
+require_relative "../smartest"
+
+module Smartest
+  module Rails
+    class TestServer
+      DEFAULT_READY_TIMEOUT = 10
+
+      attr_reader :host, :port
+
+      def initialize(app:, host: nil, port: nil)
+        @app = app
+        @host = host || "127.0.0.1"
+        @requested_port = port ? port.to_i : 0
+        @server = Puma::Server.new(@app)
+        @port = bind_tcp_listener
+        @thread = nil
+      end
+
+      def start
+        @thread ||= @server.run
+      end
+
+      def stop
+        @server.stop
+      end
+
+      def wait_for_ready(timeout: DEFAULT_READY_TIMEOUT)
+        Timeout.timeout(timeout) do
+          sleep 0.05 until responsive?
+        end
+      rescue Timeout::Error
+        raise "Rails test server did not become ready at #{base_url} within #{timeout} seconds"
+      end
+
+      def wait_for_stopped(timeout: DEFAULT_READY_TIMEOUT)
+        return unless @thread
+        return if @thread.join(timeout)
+
+        raise "Rails test server did not stop within #{timeout} seconds"
+      end
+
+      def base_url
+        "http://#{host}:#{port}"
+      end
+
+      private
+
+      def bind_tcp_listener
+        listener = @server.add_tcp_listener(@host, @requested_port)
+        bound_port = listener.respond_to?(:addr) ? listener.addr[1] : @requested_port
+
+        return bound_port if bound_port && bound_port.positive?
+
+        raise "Rails test server could not determine bound port"
+      end
+
+      def responsive?
+        Net::HTTP.start(host, port, open_timeout: 0.2, read_timeout: 0.2) do |http|
+          http.head("/")
+        end
+        true
+      rescue EOFError, IOError, Net::OpenTimeout, Net::ReadTimeout, SocketError, SystemCallError
+        false
+      end
+    end
+  end
+end

data/lib/smartest/simple_stub.rb

@@ -4,22 +4,40 @@ require "digest"
 
 module Smartest
   class SimpleStub
-    STORAGE_KEY = :__smartest_simple_stub
+    StubEntry = Struct.new(:owner, :implementation)
 
     class AlreadyAppliedError < Smartest::Error; end
     class NotAppliedError < Smartest::Error; end
 
     class << self
       def implementation_for(klass_key, method_name)
-        current_stubs&.fetch(stub_key(klass_key, method_name), nil)
+        stub_registry_mutex.synchronize do
+          active_stubs.fetch(stub_key(klass_key, method_name), nil)&.last&.implementation
+        end
       end
 
-      def active_stubs
-        Thread.current[STORAGE_KEY] ||= {}
+      def activate_stub(stub, stub_key, implementation)
+        stub_registry_mutex.synchronize do
+          stack = active_stubs[stub_key] ||= []
+          return false if stack.any? { |entry| entry.owner.equal?(stub) }
+
+          stack << StubEntry.new(stub, implementation)
+          true
+        end
       end
 
-      def clear_active_stubs_if_empty
-        Thread.current[STORAGE_KEY] = nil if current_stubs&.empty?
+      def deactivate_stub(stub, stub_key)
+        stub_registry_mutex.synchronize do
+          stack = active_stubs.fetch(stub_key, nil)
+          return false unless stack
+
+          index = stack.index { |entry| entry.owner.equal?(stub) }
+          return false unless index
+
+          stack.delete_at(index)
+          active_stubs.delete(stub_key) if stack.empty?
+          true
+        end
       end
 
       def ensure_dispatcher_method(klass, klass_key, method_name)
@@ -45,10 +63,6 @@ module Smartest
         [klass_key, method_name]
       end
 
-      def current_stubs
-        Thread.current[STORAGE_KEY]
-      end
-
       def call_implementation(receiver, implementation, args, kwargs, block)
         return call_implementation_with_block(receiver, implementation, args, kwargs, block) if block
 
@@ -110,6 +124,14 @@ module Smartest
       def call_mutex
         @call_mutex ||= Mutex.new
       end
+
+      def active_stubs
+        @active_stubs ||= {}
+      end
+
+      def stub_registry_mutex
+        @stub_registry_mutex ||= Mutex.new
+      end
     end
 
     def initialize(klass, method_name, &implementation)
@@ -122,26 +144,10 @@ module Smartest
     end
 
     def apply
-      return if stub_defined?
-
-      apply_stub
-    end
-
-    def apply!
-      raise AlreadyAppliedError, "stub for #{@klass}##{@method_name} is already applied" if stub_defined?
-
       apply_stub
     end
 
     def reset
-      return unless stub_defined?
-
-      reset_stub
-    end
-
-    def reset!
-      raise NotAppliedError, "stub for #{@klass}##{@method_name} is not applied" unless stub_defined?
-
       reset_stub
     end
 
@@ -151,16 +157,15 @@ module Smartest
       raise ArgumentError, "block must be given for applying stub" unless @implementation
 
       self.class.ensure_dispatcher_method(@klass, klass_key, @method_name)
-      active_stubs[stub_key] = @implementation
+      return self if self.class.activate_stub(self, stub_key, @implementation)
+
+      raise AlreadyAppliedError, "stub for #{@klass}##{@method_name} is already applied"
     end
 
     def reset_stub
-      active_stubs.delete(stub_key)
-      self.class.clear_active_stubs_if_empty
-    end
+      return self if self.class.deactivate_stub(self, stub_key)
 
-    def active_stubs
-      self.class.active_stubs
+      raise NotAppliedError, "stub for #{@klass}##{@method_name} is not applied"
     end
 
     def stub_key
@@ -170,9 +175,5 @@ module Smartest
     def klass_key
       @klass_key ||= Digest::SHA256.hexdigest(@klass.object_id.to_s)
     end
-
-    def stub_defined?
-      self.class.current_stubs&.key?(stub_key)
-    end
   end
 end

data/lib/smartest/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Smartest
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/smartest.rb

@@ -28,6 +28,7 @@ require_relative "smartest/reporter"
 require_relative "smartest/runner"
 require_relative "smartest/init_generator"
 require_relative "smartest/init_browser_generator"
+require_relative "smartest/init_rails_generator"
 require_relative "smartest/cli_arguments"
 
 module Smartest

data/smartest/simple_stub_test.rb

@@ -71,7 +71,7 @@ test("simple stub stubs instance methods until reset") do
   existing = SimpleStubSelfTestSubject.new("Alice")
   stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "stubbed" }
 
-  stub.apply!
+  stub.apply
 
   begin
     expect(existing.name).to eq("stubbed")
@@ -84,13 +84,23 @@ test("simple stub stubs instance methods until reset") do
   expect(SimpleStubSelfTestSubject.new("Bob").name).to eq("original Bob")
 end
 
-test("simple stub can be reset from a fresh stub object") do
-  Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :greeting) { |prefix| "#{prefix}, stubbed" }.apply!
+test("simple stub reset requires the applied stub object") do
+  stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :greeting) do |prefix|
+    "#{prefix}, stubbed"
+  end
+
+  stub.apply
 
   begin
     expect(SimpleStubSelfTestSubject.new("Alice").greeting("Hi")).to eq("Hi, stubbed")
+
+    error = SimpleStubSelfTest.capture_error(Smartest::SimpleStub::NotAppliedError) do
+      Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :greeting).reset
+    end
+
+    expect(error.message).to eq("stub for SimpleStubSelfTestSubject#greeting is not applied")
   ensure
-    Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :greeting).reset!
+    stub.reset
   end
 
   expect(SimpleStubSelfTestSubject.new("Alice").greeting("Hi")).to eq("Hi, Alice")
@@ -127,6 +137,39 @@ test("simple_stub_any_instance_of applies and resets from fixture teardown") do
   expect(status).to eq(0)
 end
 
+test("test-scoped method stubs restore suite-scoped method stubs") do
+  fixture_class = Class.new(Smartest::Fixture) do
+    suite_fixture :suite_name_stub do
+      simple_stub_any_instance_of(SimpleStubSelfTestSubject, :name) { "suite #{@name}" }
+    end
+
+    fixture :test_name_stub do |suite_name_stub:|
+      expect(suite_name_stub).to be_a(Smartest::SimpleStub)
+      simple_stub_any_instance_of(SimpleStubSelfTestSubject, :name) { "test #{@name}" }
+    end
+  end
+
+  suite = Smartest::Suite.new
+  suite.fixture_classes.add(fixture_class)
+  suite.tests.add(
+    SimpleStubSelfTest.test_case(
+      "uses test scoped override",
+      proc { |test_name_stub:| expect(SimpleStubSelfTestSubject.new("Alice").name).to eq("test Alice") }
+    )
+  )
+  suite.tests.add(
+    SimpleStubSelfTest.test_case(
+      "sees suite scoped stub after override teardown",
+      proc { |suite_name_stub:| expect(SimpleStubSelfTestSubject.new("Alice").name).to eq("suite Alice") }
+    )
+  )
+
+  status, = SimpleStubSelfTest.run_suite(suite)
+
+  expect(status).to eq(0)
+  expect(SimpleStubSelfTestSubject.new("Alice").name).to eq("original Alice")
+end
+
 test("simple_stub applies and resets singleton methods from fixture teardown") do
   fixture_class = Class.new(Smartest::Fixture) do
     fixture :stubbed_time do
@@ -261,7 +304,7 @@ test("simple stub preserves receiver self and method blocks") do
     block.call("#{prefix}, stubbed #{@name}")
   end
 
-  stub.apply!
+  stub.apply
 
   begin
     result = subject.yielding_greeting("Hi") { |message| message.upcase }
@@ -273,16 +316,16 @@ test("simple stub preserves receiver self and method blocks") do
   expect(subject.yielding_greeting("Hi") { |message| message }).to eq("Hi, Alice")
 end
 
-test("simple stub is scoped to the current fiber") do
+test("simple stub is shared with fibers") do
   subject = SimpleStubSelfTestSubject.new("Alice")
   stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "stubbed #{@name}" }
 
-  stub.apply!
+  stub.apply
 
   begin
     expect(subject.name).to eq("stubbed Alice")
     Fiber.new do
-      expect(subject.name).to eq("original Alice")
+      expect(subject.name).to eq("stubbed Alice")
     end.resume
   ensure
     stub.reset
@@ -291,52 +334,62 @@ test("simple stub is scoped to the current fiber") do
   expect(subject.name).to eq("original Alice")
 end
 
-test("simple stub can differ per thread") do
+test("simple stub is shared with threads") do
   subject = SimpleStubSelfTestSubject.new("Alice")
   queue = Queue.new
-  main_stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "main #{@name}" }
+  stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "stubbed #{@name}" }
 
-  main_stub.apply!
+  stub.apply
 
   thread = Thread.new do
-    thread_stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "thread #{@name}" }
-    thread_stub.apply!
-
-    begin
-      queue << subject.name
-    rescue Exception => error
-      queue << error
-    ensure
-      thread_stub.reset
-    end
+    queue << subject.name
+  rescue Exception => error
+    queue << error
   end
 
   begin
-    expect(subject.name).to eq("main Alice")
+    expect(subject.name).to eq("stubbed Alice")
 
     thread_result = queue.pop
     raise thread_result if thread_result.is_a?(Exception)
 
-    expect(thread_result).to eq("thread Alice")
+    expect(thread_result).to eq("stubbed Alice")
     thread.join
-    expect(subject.name).to eq("main Alice")
   ensure
-    main_stub.reset
+    stub.reset
     thread.kill if thread.alive?
   end
 
   expect(subject.name).to eq("original Alice")
 end
 
-test("simple stub supports safe and strict apply reset APIs") do
+test("simple stub restores previous implementation when nested stubs reset") do
+  subject = SimpleStubSelfTestSubject.new("Alice")
+  outer_stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "outer #{@name}" }
+  inner_stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "inner #{@name}" }
+
+  outer_stub.apply
+  inner_stub.apply
+
+  begin
+    expect(subject.name).to eq("inner Alice")
+    inner_stub.reset
+    expect(subject.name).to eq("outer Alice")
+  ensure
+    outer_stub.reset
+  end
+
+  expect(subject.name).to eq("original Alice")
+end
+
+test("simple stub apply and reset are strict") do
   stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "stubbed" }
 
-  stub.apply
   stub.apply
 
   begin
     error = SimpleStubSelfTest.capture_error(Smartest::SimpleStub::AlreadyAppliedError) do
-      Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "other" }.apply!
+      stub.apply
     end
 
     expect(error.message).to eq("stub for SimpleStubSelfTestSubject#name is already applied")
@@ -344,10 +397,8 @@ test("simple stub supports safe and strict apply reset APIs") do
     stub.reset
   end
 
-  stub.reset
-
   error = SimpleStubSelfTest.capture_error(Smartest::SimpleStub::NotAppliedError) do
-    stub.reset!
+    stub.reset
   end
 
   expect(error.message).to eq("stub for SimpleStubSelfTestSubject#name is not applied")
@@ -367,7 +418,7 @@ test("simple stub validates constructor arguments and apply block") do
   expect(error.message).to eq("method name must be a Symbol.")
 
   error = SimpleStubSelfTest.capture_error(ArgumentError) do
-    Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name).apply!
+    Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name).apply
   end
 
   expect(error.message).to eq("block must be given for applying stub")

data/smartest/smartest_test.rb

@@ -9,6 +9,8 @@ require "open3"
 require "tmpdir"
 
 module SmartestSelfTest
+  ENV_MISSING = Object.new.freeze
+
   module_function
 
   def test_case(name, block)
@@ -40,6 +42,20 @@ module SmartestSelfTest
   else
     raise Smartest::AssertionFailed, "expected #{expected_error}, but nothing was raised"
   end
+
+  def with_env(values)
+    previous_values = {}
+    values.each do |key, value|
+      previous_values[key] = ENV.fetch(key, ENV_MISSING)
+      value.nil? ? ENV.delete(key) : ENV[key] = value
+    end
+
+    yield
+  ensure
+    previous_values.each do |key, value|
+      value.equal?(ENV_MISSING) ? ENV.delete(key) : ENV[key] = value
+    end
+  end
 end
 
 class SelfTestRegisteredFixture < Smartest::Fixture
@@ -1723,6 +1739,7 @@ test("cli prints help") do
   expect(stdout).not_to include("Run a browser test file")
   expect(stdout).to include("bundle exec smartest --init")
   expect(stdout).to include("bundle exec smartest --init-browser")
+  expect(stdout).to include("bundle exec smartest --init-rails")
   expect(stdout).to include("--profile N")
   expect(stdout).to include("smartest/**/*_test.rb")
 end
@@ -1741,6 +1758,7 @@ test("cli explains how to initialize when default smartest directory is missing"
     expect(stdout).to include("No smartest/ directory found.")
     expect(stdout).to include("bundle exec smartest --init")
     expect(stdout).to include("bundle exec smartest --init-browser")
+    expect(stdout).to include("bundle exec smartest --init-rails")
     expect(stdout).to include("bundle exec smartest --help")
   end
 end
@@ -2198,3 +2216,274 @@ test("cli browser init generator skips npm init when package.json already exists
     expect(output.string).not_to include("npm init --yes")
   end
 end
+
+test("smartest rails helper is loaded only by explicit require") do
+  lib_path = File.expand_path("../lib", __dir__)
+  stdout, stderr, status = Open3.capture3(
+    { "RUBYLIB" => lib_path },
+    "ruby",
+    "-e",
+    'require "smartest"; puts Smartest.const_defined?(:Rails, false)'
+  )
+
+  expect(status.success?).to eq(true)
+  expect(stderr).to eq("")
+  expect(stdout).to eq("false\n")
+
+  Dir.mktmpdir do |dir|
+    File.write(File.join(dir, "puma.rb"), "module Puma\n  class Server\n  end\nend\n")
+
+    stdout, stderr, status = Open3.capture3(
+      { "RUBYLIB" => "#{dir}:#{lib_path}" },
+      "ruby",
+      "-e",
+      'require "smartest/rails"; puts Smartest::Rails.const_defined?(:TestServer, false)'
+    )
+
+    expect(status.success?).to eq(true)
+    expect(stderr).to eq("")
+    expect(stdout).to eq("true\n")
+  end
+end
+
+test("smartest rails test server wraps puma with explicit arguments and lifecycle") do
+  lib_path = File.expand_path("../lib", __dir__)
+
+  Dir.mktmpdir do |dir|
+    File.write(File.join(dir, "puma.rb"), <<~RUBY)
+      module Puma
+        class Listener
+          def initialize(port)
+            @port = port
+          end
+
+          def addr
+            ["AF_INET", @port]
+          end
+        end
+
+        class Server
+          attr_reader :stopped
+
+          def initialize(app)
+            @app = app
+          end
+
+          def add_tcp_listener(_host, port)
+            Listener.new(port.zero? ? 4321 : port)
+          end
+
+          def run
+            Thread.new {}
+          end
+
+          def stop
+            @stopped = true
+          end
+        end
+      end
+    RUBY
+
+    stdout, stderr, status = Open3.capture3(
+      {
+        "RUBYLIB" => "#{dir}:#{lib_path}",
+        "SMARTEST_RAILS_TEST_SERVER_HOST" => "0.0.0.0",
+        "SMARTEST_RAILS_TEST_SERVER_PORT" => "9876",
+        "SMARTEST_RAILS_BASE_URL" => "http://app:9876"
+      },
+      "ruby",
+      "-e",
+      <<~'RUBY'
+        require "smartest/rails"
+
+        server = Smartest::Rails::TestServer.new(app: Object.new, port: "4567")
+        default_port_server = Smartest::Rails::TestServer.new(app: Object.new)
+        thread = server.start
+        server.stop
+        server.wait_for_stopped
+
+        puts server.base_url
+        puts default_port_server.base_url
+        puts thread.is_a?(Thread)
+      RUBY
+    )
+
+    expect(status.success?).to eq(true)
+    expect(stderr).to eq("")
+    expect(stdout).to eq("http://127.0.0.1:4567\nhttp://127.0.0.1:4321\ntrue\n")
+  end
+end
+
+test("cli rails init generator creates Rails browser scaffold and installation commands") do
+  Dir.mktmpdir do |dir|
+    File.write(File.join(dir, "Gemfile"), <<~RUBY)
+      source "https://rubygems.org"
+
+      gem "rails"
+      gem "smartest"
+    RUBY
+
+    commands = []
+    output = StringIO.new
+    generator = Smartest::InitRailsGenerator.new(
+      root: dir,
+      output: output,
+      command_runner: ->(command, chdir:) {
+        commands << [command, chdir]
+        true
+      }
+    )
+
+    status = generator.run
+
+    expect(status).to eq(0)
+    rails_fixture = File.read(File.join(dir, "smartest/fixtures/rails_system_fixture.rb"))
+    expect(rails_fixture).to include("require 'smartest/rails'")
+    expect(rails_fixture).to include("class RailsSystemTestFixture < Smartest::Fixture")
+    expect(rails_fixture).to include("suite_fixture :rails_server")
+    expect(rails_fixture).to include("server cannot boot against the development database")
+    expect(rails_fixture).to include('require_relative "../../config/environment"')
+    expect(rails_fixture).to include("Smartest::Rails::TestServer.new(")
+    expect(rails_fixture).to include('host: ENV["SMARTEST_RAILS_TEST_SERVER_HOST"]')
+    expect(rails_fixture).not_to include("bind_host:")
+    expect(rails_fixture).to include('port: ENV["SMARTEST_RAILS_TEST_SERVER_PORT"]')
+    expect(rails_fixture).not_to include("public_base_url")
+    expect(rails_fixture).not_to include("SmartestRailsTestServer")
+    expect(rails_fixture).not_to include("Puma::Server")
+    expect(rails_fixture).to include("suite_fixture :base_url")
+    expect(rails_fixture).to include('ENV.fetch("SMARTEST_RAILS_BASE_URL", rails_server.base_url)')
+    expect(rails_fixture).not_to include("rails_test_server_port")
+    expect(rails_fixture).not_to include("SMARTEST_RAILS_PORT")
+    expect(rails_fixture).to include('ws_endpoint = ENV["PLAYWRIGHT_WS_ENDPOINT"]')
+    expect(rails_fixture).not_to include("suite_fixture :playwright_execution")
+    expect(rails_fixture).not_to include("suite_fixture :playwright do")
+    expect(rails_fixture).not_to include("Playwright.connect_to_playwright_server")
+    expect(rails_fixture).not_to include("rescue NotImplementedError")
+    expect(rails_fixture).to include("playwright_execution = Playwright.connect_to_browser_server(")
+    expect(rails_fixture).to include("browser_type: selected_browser_type.to_s")
+    expect(rails_fixture).to include("playwright_execution.browser")
+    expect(rails_fixture).to include('ENV.fetch(')
+    expect(rails_fixture).to include('"PLAYWRIGHT_CLI_EXECUTABLE_PATH"')
+    expect(rails_fixture).to include("suite_fixture :browser do")
+    expect(rails_fixture).to include("playwright_execution = Playwright.create(")
+    expect(rails_fixture).to include("on_teardown { playwright_execution.stop }")
+    expect(rails_fixture).to include("playwright = playwright_execution.playwright")
+    expect(rails_fixture).to include("playwright.public_send(selected_browser_type).launch(**browser_launch_options)")
+    expect(rails_fixture).to include("def selected_browser_type")
+    expect(rails_fixture).to include("def browser_launch_options")
+    expect(rails_fixture).to include("fixture :browser_context do |base_url:, browser:|")
+    expect(rails_fixture).to include("context = browser.new_context(baseURL: base_url)")
+    expect(rails_fixture).to include("fixture :page do |browser_context:|")
+
+    example_test = File.read(File.join(dir, "smartest/example_rails_system_test.rb"))
+    expect(example_test).to include('test("loads the Rails application") do |page:|')
+    expect(example_test).to include('response = page.goto("/")')
+    expect(example_test).to include("expect(response.status).to be_between(200, 599)")
+
+    helper_contents = File.read(File.join(dir, "smartest/test_helper.rb"))
+    expect(helper_contents).to include("use_matcher PredicateMatcher\n  use_fixture RailsSystemTestFixture\n  use_matcher PlaywrightMatcher\n  suite.run")
+    expect(helper_contents).not_to include("Smartest::SimpleStub")
+
+    gemfile_contents = File.read(File.join(dir, "Gemfile"))
+    expect(gemfile_contents).to include('gem "playwright-ruby-client", group: :test')
+    expect(commands).to eq(
+      [
+        [["bundle", "install"], dir],
+        [["npm", "init", "--yes"], dir],
+        [["npm", "install", "playwright", "--save-dev"], dir],
+        [["./node_modules/.bin/playwright", "install"], dir]
+      ]
+    )
+    expect(output.string).to include("Run your Rails browser test suite with: bundle exec smartest smartest/example_rails_system_test.rb")
+  end
+end
+
+test("cli rails init generator skips browser install when requested by environment") do
+  SmartestSelfTest.with_env("SMARTEST_SKIP_BROWSER_DOWNLOAD" => "1") do
+    Dir.mktmpdir do |dir|
+      File.write(File.join(dir, "Gemfile"), <<~RUBY)
+        source "https://rubygems.org"
+
+        gem "rails"
+        gem "smartest"
+      RUBY
+
+      commands = []
+      output = StringIO.new
+      generator = Smartest::InitRailsGenerator.new(
+        root: dir,
+        output: output,
+        command_runner: ->(command, chdir:) {
+          commands << [command, chdir]
+          true
+        }
+      )
+
+      status = generator.run
+
+      expect(status).to eq(0)
+      expect(commands).to eq(
+        [
+          [["bundle", "install"], dir],
+          [["npm", "init", "--yes"], dir],
+          [["npm", "install", "playwright", "--save-dev"], dir]
+        ]
+      )
+      expect(output.string).to include("skip    ./node_modules/.bin/playwright install (SMARTEST_SKIP_BROWSER_DOWNLOAD=1)")
+      expect(File.exist?(File.join(dir, "smartest/fixtures/rails_system_fixture.rb"))).to eq(true)
+      expect(File.exist?(File.join(dir, "smartest/example_rails_system_test.rb"))).to eq(true)
+    end
+  end
+end
+
+test("cli rails init generator skips duplicate registration and dependencies") do
+  Dir.mktmpdir do |dir|
+    FileUtils.mkdir_p(File.join(dir, "smartest/fixtures"))
+    FileUtils.mkdir_p(File.join(dir, "smartest/matchers"))
+    File.write(File.join(dir, "package.json"), "{\n  \"name\": \"existing\"\n}\n")
+    File.write(File.join(dir, "Gemfile"), <<~RUBY)
+      source "https://rubygems.org"
+
+      gem "smartest"
+      gem "playwright-ruby-client", group: :test
+    RUBY
+    File.write(File.join(dir, "smartest/test_helper.rb"), <<~RUBY)
+      require "smartest/autorun"
+
+      around_suite do |suite|
+        use_matcher PredicateMatcher
+        use_fixture RailsSystemTestFixture
+        use_matcher PlaywrightMatcher
+        suite.run
+      end
+    RUBY
+
+    commands = []
+    output = StringIO.new
+    generator = Smartest::InitRailsGenerator.new(
+      root: dir,
+      output: output,
+      command_runner: ->(command, chdir:) {
+        commands << [command, chdir]
+        true
+      }
+    )
+
+    status = generator.run
+
+    expect(status).to eq(0)
+    helper_contents = File.read(File.join(dir, "smartest/test_helper.rb"))
+    expect(helper_contents.scan("use_fixture RailsSystemTestFixture").length).to eq(1)
+    expect(helper_contents.scan("use_matcher PlaywrightMatcher").length).to eq(1)
+    expect(helper_contents).not_to include("Smartest::SimpleStub")
+    expect(commands).to eq(
+      [
+        [["bundle", "install"], dir],
+        [["npm", "install", "playwright", "--save-dev"], dir],
+        [["./node_modules/.bin/playwright", "install"], dir]
+      ]
+    )
+    expect(output.string).to include("exist   Gemfile playwright-ruby-client")
+    expect(output.string).not_to include("npm init --yes")
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smartest
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Yusuke Iwaki
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-07 00:00:00.000000000 Z
+date: 2026-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -62,9 +62,11 @@ files:
 - lib/smartest/hook_contexts.rb
 - lib/smartest/init_browser_generator.rb
 - lib/smartest/init_generator.rb
+- lib/smartest/init_rails_generator.rb
 - lib/smartest/matcher_registry.rb
 - lib/smartest/matchers.rb
 - lib/smartest/parameter_extractor.rb
+- lib/smartest/rails.rb
 - lib/smartest/reporter.rb
 - lib/smartest/runner.rb
 - lib/smartest/simple_stub.rb