smartest 0.3.3.alpha1 → 0.3.3.alpha3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e7e25cbb3432e62d6264a3308b1b8f01406ed44362f742356b31aa31629926a
-  data.tar.gz: cbb07c4ae5e9532836d505543f1af85ea222fd013d65b3fa79d0de0228fac1e6
+  metadata.gz: 46365bf842594d74023e6c47da5b98f28e2f8ad765a035de09a54f5d127db2ee
+  data.tar.gz: 53134bcd0052d5cd8b495b36a9ba8bb1344c6dcb0626d0547dfa49bf6eff005e
 SHA512:
-  metadata.gz: 5d8cc3fde5695e83649858389212a849ded911ff350689747a62a53ae4c0ce7da5c800e8d6866fb46b04756d0f890efaa3107e9e0bed642092cf2f42aa01bb63
-  data.tar.gz: dbd5c2b3fab3d0ab182c78d2ee8f60dbb71efe61e0779646bea2194d1e2710bc3baf6c307b046500dcb293446bcd49a1a1c119c09df22703a9805f83992b7780
+  metadata.gz: a5ffe755697e79babe4e54e52d9a2e2a13aee1ade7306dfa7adffd7d9ea6ca75b7b96825b05c713261f420f35b28e980a85b068a94823109bffc0a54774d864a
+  data.tar.gz: c030cd6bfcfb44f8273348f99a36a6213c237c9bd580cd49287351b4bf9b70a04af3b6b7889287f12ffbda747dfd7d6a450b9954bf51f8c2bdf5fb71768027ba

data/DEVELOPMENT.md

@@ -45,6 +45,7 @@ smartest/
       expectations.rb
       expectation_target.rb
       matchers.rb
+      simple_stub.rb
 
       runner.rb
       test_result.rb

data/README.md

@@ -600,6 +600,61 @@ end
 
 Register cleanup immediately after acquiring the resource, before later setup steps that may fail.
 
+## Stubs
+
+Use simple stub helpers when a fixture needs to temporarily replace a Ruby
+method and reset it during cleanup:
+
+```ruby
+class PaymentFixture < Smartest::Fixture
+  fixture :payment_gateway_stub do
+    simple_stub_any_instance_of(PaymentGateway, :charge) { :approved }
+  end
+end
+```
+
+Register the fixture class from `around_suite` before tests request the fixture:
+
+```ruby
+around_suite do |suite|
+  use_fixture PaymentFixture
+  suite.run
+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:
+
+```ruby
+test("checkout succeeds") do |payment_gateway_stub:|
+  expect(Checkout.call).to eq(:paid)
+end
+```
+
+Use `simple_stub(Time, :now) { fixed_time }` for singleton methods such as class
+methods. Use `simple_stub_const("AppConfig::PAYMENT_PROVIDER", "fake")` for
+constants. Constant stubs are process-global; avoid concurrent tests that stub
+the same constant.
+
+The method stub helpers call `Smartest::SimpleStub` internally, apply the stub,
+register `cleanup { stub.reset }`, and return the stub object.
+`simple_stub_const` records the previous constant value, replaces it, and
+restores or removes it during cleanup. These helpers are available inside
+`Smartest::Fixture` fixture blocks because they need cleanup to tie the stub
+lifetime to the fixture scope.
+
+`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).
+
 ## Logged-in client example
 
 ```ruby
@@ -825,6 +880,7 @@ Smartest currently focuses on a small runner API:
 - fixture dependencies through keyword arguments
 - fixture cleanup
 - suite-scoped fixtures through `suite_fixture`
+- fixture-scoped method and constant stubs
 - suite hooks with `around_suite`
 - test hooks with `around_test`
 - skipped and pending tests through `skip` and `pending`

data/lib/smartest/fixture.rb

@@ -65,6 +65,56 @@ module Smartest
       @fixture_set.add_cleanup(&block)
     end
 
+    def simple_stub_any_instance_of(klass, method_name, &block)
+      apply_simple_stub(SimpleStub.new(klass, method_name, &block))
+    end
+
+    def simple_stub(object, method_name, &block)
+      apply_simple_stub(SimpleStub.new(object.singleton_class, method_name, &block))
+    end
+
+    def simple_stub_const(constant_path, value)
+      owner, constant_name = resolve_simple_stub_constant(constant_path)
+      original_defined = owner.const_defined?(constant_name, false)
+      original_value = owner.const_get(constant_name, false) if original_defined
+
+      owner.__send__(:remove_const, constant_name) if original_defined
+      owner.const_set(constant_name, value)
+
+      cleanup do
+        owner.__send__(:remove_const, constant_name) if owner.const_defined?(constant_name, false)
+        owner.const_set(constant_name, original_value) if original_defined
+      end
+
+      value
+    end
+
+    def apply_simple_stub(stub)
+      stub.apply!
+      cleanup { stub.reset }
+      stub
+    end
+
+    def resolve_simple_stub_constant(constant_path)
+      unless constant_path.is_a?(String) || constant_path.is_a?(Symbol)
+        raise ArgumentError, "constant path must be a String or Symbol"
+      end
+
+      names = constant_path.to_s.split("::")
+      names.shift if names.first == ""
+      raise ArgumentError, "constant path must not be empty" if names.empty?
+
+      names.each do |name|
+        raise ArgumentError, "invalid constant path: #{constant_path}" unless name.match?(/\A[A-Z]\w*\z/)
+      end
+
+      constant_name = names.pop.to_sym
+      owner = names.reduce(Object) { |namespace, name| namespace.const_get(name, false) }
+      raise ArgumentError, "constant owner must be a Module or Class" unless owner.is_a?(Module)
+
+      [owner, constant_name]
+    end
+
     def method_missing(method_name, *args, &block)
       return super if RESERVED_CONTEXT_METHODS.include?(method_name)
 

data/lib/smartest/simple_stub.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Smartest
+  class SimpleStub
+    STORAGE_KEY = :__smartest_simple_stub
+
+    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)
+      end
+
+      def active_stubs
+        Thread.current[STORAGE_KEY] ||= {}
+      end
+
+      def clear_active_stubs_if_empty
+        Thread.current[STORAGE_KEY] = nil if current_stubs&.empty?
+      end
+
+      def ensure_dispatcher_method(klass, klass_key, method_name)
+        dispatcher_mutex.synchronize do
+          mod = dispatcher_module_for(klass, klass_key)
+          next if mod.method_defined?(method_name) || mod.private_method_defined?(method_name)
+
+          mod.define_method(method_name) do |*args, **kwargs, &block|
+            implementation = SimpleStub.implementation_for(klass_key, method_name)
+
+            if implementation
+              SimpleStub.call_implementation(self, implementation, args, kwargs, block)
+            elsif kwargs.empty?
+              super(*args, &block)
+            else
+              super(*args, **kwargs, &block)
+            end
+          end
+        end
+      end
+
+      def stub_key(klass_key, method_name)
+        [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
+
+        if kwargs.empty?
+          receiver.instance_exec(*args, &implementation)
+        else
+          receiver.instance_exec(*args, **kwargs, &implementation)
+        end
+      end
+
+      def call_implementation_with_block(receiver, implementation, args, kwargs, block)
+        method_name = next_call_method_name
+        singleton_class = receiver.singleton_class
+        singleton_class.__send__(:define_method, method_name, &implementation)
+
+        if kwargs.empty?
+          receiver.__send__(method_name, *args, &block)
+        else
+          receiver.__send__(method_name, *args, **kwargs, &block)
+        end
+      ensure
+        if singleton_class &&
+            (singleton_class.method_defined?(method_name) || singleton_class.private_method_defined?(method_name))
+          singleton_class.__send__(:remove_method, method_name)
+        end
+      end
+
+      private
+
+      def dispatcher_module_for(klass, klass_key)
+        const_name = dispatcher_module_name(klass_key)
+
+        if const_defined?(const_name, false)
+          const_get(const_name, false)
+        else
+          Module.new.tap do |mod|
+            const_set(const_name, mod)
+            klass.prepend(mod)
+          end
+        end
+      end
+
+      def dispatcher_module_name(klass_key)
+        "StubDispatcher#{klass_key}"
+      end
+
+      def dispatcher_mutex
+        @dispatcher_mutex ||= Mutex.new
+      end
+
+      def next_call_method_name
+        call_mutex.synchronize do
+          @call_sequence ||= 0
+          @call_sequence += 1
+          :"__smartest_simple_stub_call_#{@call_sequence}"
+        end
+      end
+
+      def call_mutex
+        @call_mutex ||= Mutex.new
+      end
+    end
+
+    def initialize(klass, method_name, &implementation)
+      raise ArgumentError, "klass must be a Class. #{klass.class} specified." unless klass.is_a?(Class)
+      raise ArgumentError, "method name must be a Symbol." unless method_name.is_a?(Symbol)
+
+      @klass = klass
+      @method_name = method_name
+      @implementation = implementation
+    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
+
+    private
+
+    def apply_stub
+      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
+    end
+
+    def reset_stub
+      active_stubs.delete(stub_key)
+      self.class.clear_active_stubs_if_empty
+    end
+
+    def active_stubs
+      self.class.active_stubs
+    end
+
+    def stub_key
+      self.class.stub_key(klass_key, @method_name)
+    end
+
+    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.3.3.alpha1"
+  VERSION = "0.3.3.alpha3"
 end

data/lib/smartest.rb

@@ -2,6 +2,7 @@
 
 require_relative "smartest/version"
 require_relative "smartest/errors"
+require_relative "smartest/simple_stub"
 require_relative "smartest/parameter_extractor"
 require_relative "smartest/test_case"
 require_relative "smartest/test_registry"

data/smartest/simple_stub_test.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "smartest/autorun"
+require "stringio"
+
+module SimpleStubSelfTest
+  module_function
+
+  def test_case(name, block)
+    Smartest::TestCase.new(
+      name: name,
+      metadata: {},
+      block: block,
+      location: caller_locations(1, 1).first
+    )
+  end
+
+  def run_suite(suite)
+    output = StringIO.new
+    status = Smartest::Runner.new(suite: suite, reporter: Smartest::Reporter.new(output)).run
+
+    [status, output.string]
+  end
+
+  def capture_error(expected_error)
+    yield
+  rescue Exception => error
+    raise if Smartest.fatal_exception?(error)
+
+    unless error.is_a?(expected_error)
+      raise Smartest::AssertionFailed, "expected #{expected_error}, but raised #{error.class}: #{error.message}"
+    end
+
+    error
+  else
+    raise Smartest::AssertionFailed, "expected #{expected_error}, but nothing was raised"
+  end
+end
+
+class SimpleStubSelfTestSubject
+  def initialize(name)
+    @name = name
+  end
+
+  def name
+    "original #{@name}"
+  end
+
+  def greeting(prefix)
+    "#{prefix}, #{@name}"
+  end
+
+  def yielding_greeting(prefix)
+    yield "#{prefix}, #{@name}"
+  end
+end
+
+class SimpleStubSelfTestClock
+  def self.now
+    :original_now
+  end
+end
+
+module SimpleStubSelfTestConfig
+  PROVIDER = :original_provider
+end
+
+test("simple stub stubs instance methods until reset") do
+  existing = SimpleStubSelfTestSubject.new("Alice")
+  stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "stubbed" }
+
+  stub.apply!
+
+  begin
+    expect(existing.name).to eq("stubbed")
+    expect(SimpleStubSelfTestSubject.new("Bob").name).to eq("stubbed")
+  ensure
+    stub.reset
+  end
+
+  expect(existing.name).to eq("original Alice")
+  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!
+
+  begin
+    expect(SimpleStubSelfTestSubject.new("Alice").greeting("Hi")).to eq("Hi, stubbed")
+  ensure
+    Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :greeting).reset!
+  end
+
+  expect(SimpleStubSelfTestSubject.new("Alice").greeting("Hi")).to eq("Hi, Alice")
+end
+
+test("simple_stub_any_instance_of applies and resets from fixture cleanup") do
+  fixture_class = Class.new(Smartest::Fixture) do
+    fixture :stubbed_name do
+      simple_stub_any_instance_of(SimpleStubSelfTestSubject, :name) { "fixture #{@name}" }
+      :stubbed_name
+    end
+  end
+
+  suite = Smartest::Suite.new
+  suite.fixture_classes.add(fixture_class)
+  suite.tests.add(
+    SimpleStubSelfTest.test_case(
+      "uses instance stub fixture",
+      proc do |stubbed_name:|
+        expect(stubbed_name).to eq(:stubbed_name)
+        expect(SimpleStubSelfTestSubject.new("Alice").name).to eq("fixture Alice")
+      end
+    )
+  )
+  suite.tests.add(
+    SimpleStubSelfTest.test_case(
+      "sees reset instance method",
+      proc { expect(SimpleStubSelfTestSubject.new("Alice").name).to eq("original Alice") }
+    )
+  )
+
+  status, = SimpleStubSelfTest.run_suite(suite)
+
+  expect(status).to eq(0)
+end
+
+test("simple_stub applies and resets singleton methods from fixture cleanup") do
+  fixture_class = Class.new(Smartest::Fixture) do
+    fixture :stubbed_time do
+      simple_stub(SimpleStubSelfTestClock, :now) { :stubbed_now }
+      :stubbed_time
+    end
+  end
+
+  suite = Smartest::Suite.new
+  suite.fixture_classes.add(fixture_class)
+  suite.tests.add(
+    SimpleStubSelfTest.test_case(
+      "uses singleton stub fixture",
+      proc do |stubbed_time:|
+        expect(stubbed_time).to eq(:stubbed_time)
+        expect(SimpleStubSelfTestClock.now).to eq(:stubbed_now)
+      end
+    )
+  )
+  suite.tests.add(
+    SimpleStubSelfTest.test_case(
+      "sees reset singleton method",
+      proc { expect(SimpleStubSelfTestClock.now).to eq(:original_now) }
+    )
+  )
+
+  status, = SimpleStubSelfTest.run_suite(suite)
+
+  expect(status).to eq(0)
+end
+
+test("simple_stub_const applies and resets existing constants from fixture cleanup") do
+  fixture_class = Class.new(Smartest::Fixture) do
+    fixture :stubbed_provider do
+      simple_stub_const("SimpleStubSelfTestConfig::PROVIDER", :stubbed_provider)
+    end
+  end
+
+  suite = Smartest::Suite.new
+  suite.fixture_classes.add(fixture_class)
+  suite.tests.add(
+    SimpleStubSelfTest.test_case(
+      "uses constant stub fixture",
+      proc do |stubbed_provider:|
+        expect(stubbed_provider).to eq(:stubbed_provider)
+        expect(SimpleStubSelfTestConfig::PROVIDER).to eq(:stubbed_provider)
+      end
+    )
+  )
+  suite.tests.add(
+    SimpleStubSelfTest.test_case(
+      "sees restored constant",
+      proc { expect(SimpleStubSelfTestConfig::PROVIDER).to eq(:original_provider) }
+    )
+  )
+
+  status, = SimpleStubSelfTest.run_suite(suite)
+
+  expect(status).to eq(0)
+end
+
+test("simple_stub_const removes newly defined constants from fixture cleanup") do
+  fixture_class = Class.new(Smartest::Fixture) do
+    fixture :stubbed_missing_provider do
+      simple_stub_const("SimpleStubSelfTestConfig::MISSING_PROVIDER", :stubbed_missing_provider)
+    end
+  end
+
+  suite = Smartest::Suite.new
+  suite.fixture_classes.add(fixture_class)
+  suite.tests.add(
+    SimpleStubSelfTest.test_case(
+      "uses new constant stub fixture",
+      proc do |stubbed_missing_provider:|
+        expect(stubbed_missing_provider).to eq(:stubbed_missing_provider)
+        expect(SimpleStubSelfTestConfig::MISSING_PROVIDER).to eq(:stubbed_missing_provider)
+      end
+    )
+  )
+  suite.tests.add(
+    SimpleStubSelfTest.test_case(
+      "sees removed constant",
+      proc { expect(SimpleStubSelfTestConfig.const_defined?(:MISSING_PROVIDER, false)).to eq(false) }
+    )
+  )
+
+  status, = SimpleStubSelfTest.run_suite(suite)
+
+  expect(status).to eq(0)
+end
+
+test("simple stub preserves receiver self and method blocks") do
+  subject = SimpleStubSelfTestSubject.new("Alice")
+  stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :yielding_greeting) do |prefix, &block|
+    block.call("#{prefix}, stubbed #{@name}")
+  end
+
+  stub.apply!
+
+  begin
+    result = subject.yielding_greeting("Hi") { |message| message.upcase }
+    expect(result).to eq("HI, STUBBED ALICE")
+  ensure
+    stub.reset
+  end
+
+  expect(subject.yielding_greeting("Hi") { |message| message }).to eq("Hi, Alice")
+end
+
+test("simple stub is scoped to the current fiber") do
+  subject = SimpleStubSelfTestSubject.new("Alice")
+  stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "stubbed #{@name}" }
+
+  stub.apply!
+
+  begin
+    expect(subject.name).to eq("stubbed Alice")
+    Fiber.new do
+      expect(subject.name).to eq("original Alice")
+    end.resume
+  ensure
+    stub.reset
+  end
+
+  expect(subject.name).to eq("original Alice")
+end
+
+test("simple stub can differ per thread") do
+  subject = SimpleStubSelfTestSubject.new("Alice")
+  queue = Queue.new
+  main_stub = Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name) { "main #{@name}" }
+
+  main_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
+  end
+
+  begin
+    expect(subject.name).to eq("main Alice")
+
+    thread_result = queue.pop
+    raise thread_result if thread_result.is_a?(Exception)
+
+    expect(thread_result).to eq("thread Alice")
+    thread.join
+    expect(subject.name).to eq("main Alice")
+  ensure
+    main_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
+  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!
+    end
+
+    expect(error.message).to eq("stub for SimpleStubSelfTestSubject#name is already applied")
+  ensure
+    stub.reset
+  end
+
+  stub.reset
+
+  error = SimpleStubSelfTest.capture_error(Smartest::SimpleStub::NotAppliedError) do
+    stub.reset!
+  end
+
+  expect(error.message).to eq("stub for SimpleStubSelfTestSubject#name is not applied")
+end
+
+test("simple stub validates constructor arguments and apply block") do
+  error = SimpleStubSelfTest.capture_error(ArgumentError) do
+    Smartest::SimpleStub.new(Object.new, :name)
+  end
+
+  expect(error.message).to eq("klass must be a Class. Object specified.")
+
+  error = SimpleStubSelfTest.capture_error(ArgumentError) do
+    Smartest::SimpleStub.new(SimpleStubSelfTestSubject, "name")
+  end
+
+  expect(error.message).to eq("method name must be a Symbol.")
+
+  error = SimpleStubSelfTest.capture_error(ArgumentError) do
+    Smartest::SimpleStub.new(SimpleStubSelfTestSubject, :name).apply!
+  end
+
+  expect(error.message).to eq("block must be given for applying stub")
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smartest
 version: !ruby/object:Gem::Version
-  version: 0.3.3.alpha1
+  version: 0.3.3.alpha3
 platform: ruby
 authors:
 - Yusuke Iwaki
@@ -62,6 +62,7 @@ files:
 - lib/smartest/parameter_extractor.rb
 - lib/smartest/reporter.rb
 - lib/smartest/runner.rb
+- lib/smartest/simple_stub.rb
 - lib/smartest/suite.rb
 - lib/smartest/suite_run.rb
 - lib/smartest/test_case.rb
@@ -71,6 +72,7 @@ files:
 - lib/smartest/test_run_state.rb
 - lib/smartest/version.rb
 - smartest.gemspec
+- smartest/simple_stub_test.rb
 - smartest/smartest_test.rb
 homepage: https://smartest-rb.vercel.app
 licenses: