dexkit 0.7.0 → 0.9.0

data/lib/dex/operation/test_helpers/assertions.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    module TestHelpers
+      # --- Result assertions ---
+
+      def assert_ok(result, expected = :_not_given, msg = nil, &block)
+        assert result.ok?, msg || "Expected Ok, got Err:\n#{_dex_format_err(result)}"
+        if expected != :_not_given
+          assert_equal expected, result.value, msg || "Ok value mismatch"
+        end
+        yield result.value if block
+        result
+      end
+
+      def refute_ok(result, msg = nil)
+        refute result.ok?, msg || "Expected Err, got Ok:\n#{_dex_format_ok(result)}"
+        result
+      end
+
+      def assert_err(result, code = nil, message: nil, details: nil, msg: nil, &block)
+        assert result.error?, msg || "Expected Err, got Ok:\n#{_dex_format_ok(result)}"
+        if code
+          assert_equal code, result.code, msg || "Error code mismatch.\n#{_dex_format_err(result)}"
+        end
+        if message
+          case message
+          when Regexp
+            assert_match message, result.message, msg || "Error message mismatch.\n#{_dex_format_err(result)}"
+          else
+            assert_equal message, result.message, msg || "Error message mismatch.\n#{_dex_format_err(result)}"
+          end
+        end
+        details&.each do |key, val|
+          assert_equal val, result.details&.dig(key),
+            msg || "Error details[:#{key}] mismatch.\n#{_dex_format_err(result)}"
+        end
+        yield result.error if block
+        result
+      end
+
+      def refute_err(result, code = nil, msg: nil)
+        if code
+          if result.error?
+            refute_equal code, result.code,
+              msg || "Expected result to not have error code #{code.inspect}, but it does.\n#{_dex_format_err(result)}"
+          end
+        else
+          refute result.error?, msg || "Expected Ok, got Err:\n#{_dex_format_err(result)}"
+        end
+        result
+      end
+
+      # --- One-liner assertions ---
+
+      def assert_operation(*args, returns: :_not_given, **params)
+        klass = _dex_resolve_subject(args)
+        result = klass.new(**params).safe.call
+        assert result.ok?, "Expected operation to succeed, got Err:\n#{_dex_format_err(result)}"
+        if returns != :_not_given
+          assert_equal returns, result.value, "Return value mismatch"
+        end
+        result
+      end
+
+      def assert_operation_error(*args, message: nil, details: nil, **params)
+        klass, code = _dex_resolve_subject_and_code(args)
+        result = klass.new(**params).safe.call
+        assert result.error?, "Expected operation to fail, got Ok:\n#{_dex_format_ok(result)}"
+        if code
+          assert_equal code, result.code, "Error code mismatch.\n#{_dex_format_err(result)}"
+        end
+        if message
+          case message
+          when Regexp
+            assert_match message, result.message
+          else
+            assert_equal message, result.message
+          end
+        end
+        details&.each do |key, val|
+          assert_equal val, result.details&.dig(key)
+        end
+        result
+      end
+
+      # --- Contract assertions ---
+
+      def assert_params(*args)
+        if args.last.is_a?(Hash)
+          klass_args, type_hash = _dex_split_class_and_hash(args)
+          klass = _dex_resolve_subject(klass_args)
+          contract = klass.contract
+          type_hash.each do |name, type|
+            assert contract.params.key?(name),
+              "Expected param #{name.inspect} to be declared on #{klass.name || klass}"
+            assert_equal type, contract.params[name],
+              "Type mismatch for param #{name.inspect}"
+          end
+        else
+          klass_args, names = _dex_split_class_and_symbols(args)
+          klass = _dex_resolve_subject(klass_args)
+          contract = klass.contract
+          assert_equal names.sort, contract.params.keys.sort,
+            "Params mismatch on #{klass.name || klass}.\n  Expected: #{names.sort.inspect}\n  Actual:   #{contract.params.keys.sort.inspect}"
+        end
+      end
+
+      def assert_accepts_param(*args)
+        klass_args, names = _dex_split_class_and_symbols(args)
+        klass = _dex_resolve_subject(klass_args)
+        contract = klass.contract
+        names.each do |name|
+          assert contract.params.key?(name),
+            "Expected #{klass.name || klass} to accept param #{name.inspect}, but it doesn't.\n  Declared params: #{contract.params.keys.inspect}"
+        end
+      end
+
+      def assert_success_type(*args)
+        klass = if args.first.is_a?(Class) && args.first < Dex::Operation
+          args.shift
+        else
+          _dex_resolve_subject([])
+        end
+        expected = args.first
+        contract = klass.contract
+        assert_equal expected, contract.success,
+          "Success type mismatch on #{klass.name || klass}"
+      end
+
+      def assert_error_codes(*args)
+        klass_args, codes = _dex_split_class_and_symbols(args)
+        klass = _dex_resolve_subject(klass_args)
+        contract = klass.contract
+        assert_equal codes.sort, contract.errors.sort,
+          "Error codes mismatch on #{klass.name || klass}.\n  Expected: #{codes.sort.inspect}\n  Actual:   #{contract.errors.sort.inspect}"
+      end
+
+      def assert_contract(*args, params: nil, success: :_not_given, errors: nil)
+        klass = _dex_resolve_subject(args)
+        contract = klass.contract
+
+        if params
+          case params
+          when Array
+            assert_equal params.sort, contract.params.keys.sort, "Contract params mismatch"
+          when Hash
+            params.each do |name, type|
+              assert contract.params.key?(name), "Expected param #{name.inspect}"
+              assert_equal type, contract.params[name], "Type mismatch for param #{name.inspect}"
+            end
+          end
+        end
+
+        if success != :_not_given
+          assert_equal success, contract.success, "Contract success type mismatch"
+        end
+
+        if errors
+          assert_equal errors.sort, contract.errors.sort, "Contract error codes mismatch"
+        end
+      end
+
+      # --- Param validation assertions ---
+
+      def assert_invalid_params(*args, **params)
+        klass = _dex_resolve_subject(args)
+        assert_raises(Literal::TypeError) { klass.new(**params) }
+      end
+
+      def assert_valid_params(*args, **params)
+        klass = _dex_resolve_subject(args)
+        klass.new(**params)
+      end
+
+      # --- Async assertions ---
+
+      def assert_enqueues_operation(*args, queue: nil, **params)
+        _dex_ensure_active_job_test_helper!
+        klass = _dex_resolve_subject(args)
+        async_opts = queue ? { queue: queue } : {}
+        before_count = enqueued_jobs.size
+        klass.new(**params).async(**async_opts).call
+        new_jobs = enqueued_jobs[before_count..]
+        dex_job = new_jobs.find { |j|
+          j[:job] == Dex::Operation::DirectJob || j[:job] == Dex::Operation::RecordJob
+        }
+        assert dex_job,
+          "Expected #{klass.name || klass} to enqueue an async job, but none were enqueued"
+      end
+
+      def refute_enqueues_operation(&block)
+        _dex_ensure_active_job_test_helper!
+        before_count = enqueued_jobs.size
+        yield
+        after_count = enqueued_jobs.size
+        assert_equal before_count, after_count,
+          "Expected no operations to be enqueued, but #{after_count - before_count} were"
+      end
+
+      # --- Transaction assertions ---
+
+      def assert_rolls_back(model_class, &block)
+        count_before = model_class.count
+        assert_raises(Dex::Error) { yield }
+        assert_equal count_before, model_class.count,
+          "Expected transaction to roll back, but #{model_class.name} count changed from #{count_before} to #{model_class.count}"
+      end
+
+      def assert_commits(model_class, &block)
+        count_before = model_class.count
+        yield
+        assert count_before < model_class.count,
+          "Expected #{model_class.name} count to increase, but it stayed at #{count_before}"
+      end
+
+      # --- Guard assertions ---
+
+      def assert_callable(*args, **params)
+        klass = _dex_resolve_subject(args)
+        result = klass.callable(**params)
+        assert result.ok?, "Expected operation to be callable, but guards failed:\n#{_dex_format_err(result)}"
+        result
+      end
+
+      def refute_callable(*args, **params)
+        klass_args, codes = _dex_split_class_and_symbols(args)
+        klass = _dex_resolve_subject(klass_args)
+        code = codes.first
+        result = klass.callable(**params)
+        refute result.ok?, "Expected operation to NOT be callable, but all guards passed"
+        if code
+          failed_codes = result.details.map { |f| f[:guard] }
+          assert_includes failed_codes, code,
+            "Expected guard :#{code} to fail, but it didn't.\n  Failed guards: #{failed_codes.inspect}"
+        end
+        result
+      end
+
+      # --- Batch assertions ---
+
+      def assert_all_succeed(*args, params_list:)
+        klass = _dex_resolve_subject(args)
+        results = params_list.map { |p| klass.new(**p).safe.call }
+        failures = results.each_with_index.reject { |r, _| r.ok? }
+        if failures.any?
+          msgs = failures.map { |r, i| "  [#{i}] #{params_list[i].inspect} => #{_dex_format_err(r)}" }
+          flunk "Expected all #{results.size} calls to succeed, but #{failures.size} failed:\n#{msgs.join("\n")}"
+        end
+        results
+      end
+
+      def assert_all_fail(*args, code:, params_list:, message: nil, details: nil)
+        klass = _dex_resolve_subject(args)
+        results = params_list.map { |p| klass.new(**p).safe.call }
+        failures = results.each_with_index.reject { |r, _| r.error? && r.code == code }
+        if failures.any?
+          msgs = failures.map { |r, i|
+            status = r.ok? ? "Ok(#{r.value.inspect})" : "Err(#{r.code})"
+            "  [#{i}] #{params_list[i].inspect} => #{status}"
+          }
+          flunk "Expected all #{results.size} calls to fail with #{code.inspect}, but #{failures.size} didn't:\n#{msgs.join("\n")}"
+        end
+        results.each_with_index do |r, i|
+          if message
+            case message
+            when Regexp
+              assert_match message, r.message,
+                "Error message mismatch at [#{i}] #{params_list[i].inspect}.\n#{_dex_format_err(r)}"
+            else
+              assert_equal message, r.message,
+                "Error message mismatch at [#{i}] #{params_list[i].inspect}.\n#{_dex_format_err(r)}"
+            end
+          end
+          details&.each do |key, val|
+            assert_equal val, r.details&.dig(key),
+              "Error details[:#{key}] mismatch at [#{i}] #{params_list[i].inspect}.\n#{_dex_format_err(r)}"
+          end
+        end
+        results
+      end
+
+      private
+
+      def _dex_format_err(result)
+        return "(not an error)" unless result.respond_to?(:error?) && result.error?
+
+        lines = ["  code: #{result.code.inspect}"]
+        lines << "  message: #{result.message.inspect}" if result.message && result.message != result.code.to_s
+        lines << "  details: #{result.details.inspect}" if result.details
+        lines.join("\n")
+      end
+
+      def _dex_format_ok(result)
+        return "(not ok)" unless result.respond_to?(:ok?) && result.ok?
+
+        "  value: #{result.value.inspect}"
+      end
+
+      def _dex_resolve_subject_and_code(args)
+        if args.first.is_a?(Class) && args.first < Dex::Operation
+          klass = args.shift
+          code = args.shift
+          [klass, code]
+        elsif args.first.is_a?(Symbol)
+          [_dex_resolve_subject([]), args.shift]
+        else
+          [_dex_resolve_subject([]), nil]
+        end
+      end
+
+      def _dex_split_class_and_symbols(args)
+        if args.first.is_a?(Class) && args.first < Dex::Operation
+          [args[0..0], args[1..]]
+        else
+          [[], args]
+        end
+      end
+
+      def _dex_split_class_and_hash(args)
+        hash = args.pop
+        klass_args = args.select { |a| a.is_a?(Class) && a < Dex::Operation }
+        [klass_args, hash]
+      end
+
+      def _dex_ensure_active_job_test_helper!
+        return if respond_to?(:assert_enqueued_with)
+
+        raise "assert_enqueues_operation requires ActiveJob::TestHelper. " \
+              "Include it in your test class: `include ActiveJob::TestHelper`"
+      end
+    end
+  end
+end

data/lib/dex/operation/test_helpers/execution.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    module TestHelpers
+      def call_operation(*args, **params)
+        klass = _dex_resolve_subject(args)
+        klass.new(**params).safe.call
+      end
+
+      def call_operation!(*args, **params)
+        klass = _dex_resolve_subject(args)
+        klass.new(**params).call
+      end
+
+      private
+
+      def _dex_resolve_subject(args)
+        if args.first.is_a?(Class) && args.first < Dex::Operation
+          args.first
+        elsif _dex_test_subject
+          _dex_test_subject
+        else
+          raise ArgumentError,
+            "No operation class specified. Pass it as the first argument or use `testing MyOperation` in your test class."
+        end
+      end
+    end
+  end
+end

data/lib/dex/operation/test_helpers/stubbing.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    module TestHelpers
+      def stub_operation(klass, returns: nil, error: nil, &block)
+        raise ArgumentError, "stub_operation requires a block" unless block
+
+        opts = if error
+          { error: error }
+        else
+          { returns: returns }
+        end
+
+        Dex::Operation::TestWrapper.register_stub(klass, **opts)
+        yield
+      ensure
+        Dex::Operation::TestWrapper.clear_stub(klass)
+      end
+
+      def spy_on_operation(klass, &block)
+        spy = Spy.new(klass)
+        yield spy
+        spy
+      end
+
+      class Spy
+        def initialize(klass)
+          @klass = klass
+          @started_at = Dex::TestLog.size
+        end
+
+        def calls
+          Dex::TestLog.calls[@started_at..].select { |e| e.operation_class == @klass }
+        end
+
+        def called?
+          calls.any?
+        end
+
+        def called_once?
+          calls.size == 1
+        end
+
+        def call_count
+          calls.size
+        end
+
+        def last_result
+          calls.last&.result
+        end
+
+        def called_with?(**params)
+          calls.any? do |entry|
+            params.all? { |k, v| entry.params[k] == v }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dex/operation/test_helpers.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "../test_log"
+
+module Dex
+  class Operation
+    module TestWrapper
+      @_installed = false
+
+      class << self
+        def install!
+          return if @_installed
+
+          Dex::Operation.prepend(self)
+          @_installed = true
+        end
+
+        def installed?
+          @_installed
+        end
+
+        # Stub registry
+
+        def stubs
+          @_stubs ||= {}
+        end
+
+        def find_stub(klass)
+          stubs[klass]
+        end
+
+        def register_stub(klass, **options)
+          stubs[klass] = options
+        end
+
+        def clear_stub(klass)
+          stubs.delete(klass)
+        end
+
+        def clear_all_stubs!
+          stubs.clear
+        end
+      end
+
+      def call
+        stub = Dex::Operation::TestWrapper.find_stub(self.class)
+        return _test_apply_stub(stub) if stub
+
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = nil
+        err = nil
+
+        begin
+          result = super
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          err = e
+          raise
+        ensure
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+          _test_record_to_log(result, err, duration)
+        end
+
+        result
+      end
+
+      private
+
+      def _test_apply_stub(stub)
+        if stub[:error]
+          err_opts = stub[:error]
+          case err_opts
+          when Symbol
+            raise Dex::Error.new(err_opts)
+          when Hash
+            raise Dex::Error.new(err_opts[:code], err_opts[:message], details: err_opts[:details])
+          end
+        else
+          stub[:returns]
+        end
+      end
+
+      def _test_safe_params
+        respond_to?(:to_h) ? to_h : {}
+      rescue
+        {}
+      end
+
+      def _test_record_to_log(result, err, duration)
+        safe_result = if err
+          dex_err = if err.is_a?(Dex::Error)
+            err
+          else
+            Dex::Error.new(:exception, err.message, details: { exception_class: err.class.name })
+          end
+          Dex::Operation::Err.new(dex_err)
+        else
+          Dex::Operation::Ok.new(result)
+        end
+
+        entry = Dex::TestLog::Entry.new(
+          type: "Operation",
+          name: self.class.name || self.class.to_s,
+          operation_class: self.class,
+          params: _test_safe_params,
+          result: safe_result,
+          duration: duration,
+          caller_location: caller_locations(4, 1)&.first
+        )
+        Dex::TestLog.record(entry)
+      end
+    end
+
+    module TestHelpers
+      extend Dex::Concern
+
+      def self.included(base)
+        Dex::Operation::TestWrapper.install!
+        super
+      end
+
+      def setup
+        super
+        Dex::TestLog.clear!
+        Dex::Operation::TestWrapper.clear_all_stubs!
+      end
+
+      module ClassMethods
+        def testing(klass)
+          @_dex_test_subject = klass
+        end
+
+        def _dex_test_subject
+          return @_dex_test_subject if defined?(@_dex_test_subject) && @_dex_test_subject
+
+          superclass._dex_test_subject if superclass.respond_to?(:_dex_test_subject)
+        end
+      end
+
+      private
+
+      def _dex_test_subject
+        self.class._dex_test_subject
+      end
+    end
+  end
+end
+
+require_relative "test_helpers/execution"
+require_relative "test_helpers/assertions"
+require_relative "test_helpers/stubbing"

data/lib/dex/operation/transaction_adapter.rb

@@ -3,25 +3,44 @@
 module Dex
   class Operation
     module TransactionAdapter
+      KNOWN_ADAPTERS = %i[active_record].freeze
+
       def self.for(adapter_name)
-        case adapter_name&.to_sym
+        case normalize_name(adapter_name)
         when :active_record
           ActiveRecordAdapter
-        when :mongoid
-          MongoidAdapter
         when nil
           detect
-        else
-          raise ArgumentError, "Unknown transaction adapter: #{adapter_name}"
         end
       end
 
+      def self.known_adapters
+        KNOWN_ADAPTERS
+      end
+
+      def self.normalize_name(adapter_name)
+        return nil if adapter_name.nil?
+
+        normalized = adapter_name.to_sym
+        return normalized if KNOWN_ADAPTERS.include?(normalized)
+
+        raise ArgumentError,
+          "unknown transaction adapter: #{adapter_name.inspect}. " \
+          "Known: #{KNOWN_ADAPTERS.map(&:inspect).join(", ")}"
+      end
+
       def self.detect
-        if defined?(ActiveRecord::Base)
-          ActiveRecordAdapter
-        elsif defined?(Mongoid)
-          MongoidAdapter
-        end
+        return unless defined?(ActiveRecord::Base)
+        return unless active_record_pool?
+
+        ActiveRecordAdapter
+      end
+
+      def self.active_record_pool?
+        !ActiveRecord::Base.connection_handler.retrieve_connection_pool(
+          ActiveRecord::Base.connection_specification_name,
+          strict: false
+        ).nil?
       end
 
       module ActiveRecordAdapter
@@ -44,64 +63,6 @@ module Dex
           ActiveRecord::Rollback
         end
       end
-
-      module MongoidAdapter
-        AFTER_COMMIT_KEY = :_dex_mongoid_after_commit
-
-        def self.wrap(&block)
-          unless defined?(Mongoid)
-            raise LoadError, "Mongoid is required for transactions"
-          end
-
-          callbacks = Thread.current[AFTER_COMMIT_KEY]
-          outermost = callbacks.nil?
-
-          unless outermost
-            snapshot = callbacks.length
-            begin
-              return block.call
-            rescue rollback_exception_class
-              callbacks.slice!(snapshot..)
-              return nil
-            rescue StandardError # rubocop:disable Style/RescueStandardError
-              callbacks.slice!(snapshot..)
-              raise
-            end
-          end
-
-          Thread.current[AFTER_COMMIT_KEY] = []
-          block_completed = false
-          result = Mongoid.transaction do
-            value = block.call
-            block_completed = true
-            value
-          end
-
-          if block_completed
-            Thread.current[AFTER_COMMIT_KEY].each(&:call)
-          end
-
-          result
-        ensure
-          Thread.current[AFTER_COMMIT_KEY] = nil if outermost
-        end
-
-        # NOTE: Only detects transactions opened via MongoidAdapter.wrap (i.e. Dex operations).
-        # Ambient Mongoid.transaction blocks opened outside Dex are invisible here —
-        # the callback will fire immediately instead of deferring to the outer commit.
-        def self.after_commit(&block)
-          callbacks = Thread.current[AFTER_COMMIT_KEY]
-          if callbacks
-            callbacks << block
-          else
-            block.call
-          end
-        end
-
-        def self.rollback_exception_class
-          Mongoid::Errors::Rollback
-        end
-      end
     end
   end
 end