dexkit 0.8.0 → 0.9.0

data/lib/dex/event_test_helpers.rb

@@ -1,88 +1,3 @@
 # frozen_string_literal: true
 
-module Dex
-  class Event
-    module EventTestWrapper
-      CAPTURING_KEY = :_dex_event_capturing
-      PUBLISHED_KEY = :_dex_event_published
-
-      @_installed = false
-
-      class << self
-        include ExecutionState
-
-        def install!
-          return if @_installed
-
-          Dex::Event::Bus.singleton_class.prepend(BusInterceptor)
-          @_installed = true
-        end
-
-        def installed?
-          @_installed
-        end
-
-        def capturing?
-          (_execution_state[CAPTURING_KEY] || 0) > 0
-        end
-
-        def begin_capture!
-          _execution_state[CAPTURING_KEY] = (_execution_state[CAPTURING_KEY] || 0) + 1
-        end
-
-        def end_capture!
-          depth = (_execution_state[CAPTURING_KEY] || 0) - 1
-          _execution_state[CAPTURING_KEY] = [depth, 0].max
-        end
-
-        def published_events
-          _execution_state[PUBLISHED_KEY] ||= []
-        end
-
-        def clear_published!
-          _execution_state[PUBLISHED_KEY] = []
-        end
-      end
-
-      module BusInterceptor
-        def publish(event, sync:)
-          if Dex::Event::EventTestWrapper.capturing?
-            return if Dex::Event::Suppression.suppressed?(event.class)
-
-            Dex::Event::EventTestWrapper.published_events << event
-          else
-            super(event, sync: true)
-          end
-        end
-      end
-    end
-
-    module TestHelpers
-      def self.included(base)
-        EventTestWrapper.install!
-      end
-
-      def setup
-        super
-        EventTestWrapper.clear_published!
-        Dex::Event::Trace.clear!
-        Dex::Event::Suppression.clear!
-      end
-
-      def capture_events
-        EventTestWrapper.begin_capture!
-        yield
-      ensure
-        EventTestWrapper.end_capture!
-      end
-
-      private
-
-      def _dex_published_events
-        EventTestWrapper.published_events
-      end
-    end
-  end
-end
-
-require_relative "event_test_helpers/assertions"
+require_relative "event/test_helpers"

data/lib/dex/form/uniqueness_validator.rb

@@ -50,8 +50,12 @@ module Dex
       end
 
       def _build_query(model_class, column, value)
-        if options[:case_sensitive] == false && value.is_a?(String) && model_class.respond_to?(:arel_table)
+        return model_class.where(column => value) unless options[:case_sensitive] == false && value.is_a?(String)
+
+        if model_class.respond_to?(:arel_table)
           model_class.where(model_class.arel_table[column].lower.eq(value.downcase))
+        elsif _mongoid_model_class?(model_class)
+          model_class.where(column => /\A#{Regexp.escape(value)}\z/i)
         else
           model_class.where(column => value)
         end
@@ -78,9 +82,21 @@ module Dex
       def _exclude_current_record(query, form)
         return query unless form.record&.persisted?
 
+        if _mongoid_record?(form.record)
+          return query.where(:_id.ne => form.record.id)
+        end
+
         pk = form.record.class.primary_key
         query.where.not(pk => form.record.public_send(pk))
       end
+
+      def _mongoid_model_class?(model_class)
+        defined?(Mongoid::Document) && model_class.include?(Mongoid::Document)
+      end
+
+      def _mongoid_record?(record)
+        _mongoid_model_class?(record.class)
+      end
     end
   end
 end

data/lib/dex/operation/async_proxy.rb

@@ -27,6 +27,7 @@ module Dex
       end
 
       def enqueue_record_job
+        @operation.send(:_record_validate_backend!, async: true)
         record = Dex.record_backend.create_record(
           name: operation_class_name,
           params: serialized_params,

data/lib/dex/operation/explain.rb

@@ -45,6 +45,7 @@ module Dex
 
       def _explain_callable?(info)
         return false unless info[:guards][:passed]
+        return false if info[:record][:enabled] && info[:record][:status] == :misconfigured
 
         if info[:once][:active]
           return false if ONCE_BLOCKING_STATUSES.include?(info[:once][:status])
@@ -119,12 +120,7 @@ module Dex
         return :misconfigured if name.nil?
         return :misconfigured unless pipeline.steps.any? { |s| s.name == :record }
         return :unavailable unless Dex.record_backend
-        return :misconfigured unless Dex.record_backend.has_field?("once_key")
-
-        settings = settings_for(:once)
-        if settings[:expires_in] && !Dex.record_backend.has_field?("once_key_expires_at")
-          return :misconfigured
-        end
+        return :misconfigured unless Dex.record_backend.missing_fields(send(:_once_required_fields)).empty?
 
         existing = Dex.record_backend.find_by_once_key(key)
         return :exists if existing
@@ -171,7 +167,15 @@ module Dex
           enabled: true,
           params: settings.fetch(:params, true),
           result: settings.fetch(:result, true)
-        }
+        }.tap do |entry|
+          missing = Dex.record_backend.missing_fields(send(:_record_required_fields))
+          if missing.empty?
+            entry[:status] = :ready
+          else
+            entry[:status] = :misconfigured
+            entry[:missing_fields] = missing
+          end
+        end
       end
 
       def _explain_transaction

data/lib/dex/operation/lock_wrapper.rb

@@ -54,11 +54,24 @@ module Dex
       _lock_ensure_loaded!
       key = _lock_key
       ActiveRecord::Base.with_advisory_lock!(key, **_lock_options, &block)
-    rescue WithAdvisoryLock::FailedToAcquireLock
-      raise Dex::Error.new(:lock_timeout, "Could not acquire advisory lock: #{key}")
+    rescue => e
+      if defined?(WithAdvisoryLock::FailedToAcquireLock) && e.is_a?(WithAdvisoryLock::FailedToAcquireLock)
+        raise Dex::Error.new(:lock_timeout, "Could not acquire advisory lock: #{key}")
+      end
+
+      raise
     end
 
     def _lock_ensure_loaded!
+      unless defined?(ActiveRecord::Base)
+        raise LoadError, "advisory_lock requires ActiveRecord and is not supported in Mongoid-only apps."
+      end
+
+      unless defined?(WithAdvisoryLock::FailedToAcquireLock)
+        raise LoadError,
+          "with_advisory_lock gem is required for advisory locking. Add 'with_advisory_lock' to your Gemfile."
+      end
+
       return if ActiveRecord::Base.respond_to?(:with_advisory_lock!)
 
       raise LoadError,

data/lib/dex/operation/once_wrapper.rb

@@ -44,6 +44,7 @@ module Dex
         else
           raise ArgumentError, "pass a String key or keyword arguments matching the once props"
         end
+        _once_validate_backend!
         Dex.record_backend.update_record_by_once_key(derived, once_key: nil)
       end
 
@@ -56,6 +57,27 @@ module Dex
 
       private
 
+      def _once_required_fields
+        fields =
+          if respond_to?(:_record_required_fields, true)
+            send(:_record_required_fields)
+          else
+            []
+          end
+
+        fields << "once_key"
+        fields << "once_key_expires_at" if settings_for(:once)[:expires_in]
+        fields.uniq
+      end
+
+      def _once_validate_backend!
+        unless Dex.record_backend
+          raise "once requires a record backend (configure Dex.record_class)"
+        end
+
+        Dex.record_backend.ensure_fields!(_once_required_fields, feature: "once")
+      end
+
       def _once_validate_props!(prop_names)
         return unless respond_to?(:literal_properties)
 
@@ -112,21 +134,7 @@ module Dex
     end
 
     def _once_ensure_backend!
-      unless Dex.record_backend
-        raise "once requires a record backend (configure Dex.record_class)"
-      end
-
-      return if self.class.instance_variable_defined?(:@_once_fields_checked)
-
-      unless Dex.record_backend.has_field?("once_key")
-        raise "once requires once_key column on #{Dex.record_class}. Run the migration to add it."
-      end
-
-      if self.class.settings_for(:once)[:expires_in] && !Dex.record_backend.has_field?("once_key_expires_at")
-        raise "once with expires_in requires once_key_expires_at column on #{Dex.record_class}. Run the migration to add it."
-      end
-
-      self.class.instance_variable_set(:@_once_fields_checked, true)
+      self.class.send(:_once_validate_backend!)
     end
 
     def _once_derive_key

data/lib/dex/operation/record_backend.rb

@@ -58,6 +58,19 @@ module Dex
           attributes.select { |key, _| has_field?(key.to_s) }
         end
 
+        def missing_fields(*fields)
+          fields.flatten.uniq.reject { |field_name| has_field?(field_name) }
+        end
+
+        def ensure_fields!(*fields, feature:)
+          missing = missing_fields(*fields)
+          return if missing.empty?
+
+          raise ArgumentError,
+            "Dex record_class #{record_class} is missing required attributes for #{feature}: #{missing.join(", ")}. " \
+            "Define these attributes on #{record_class} or disable #{feature}."
+        end
+
         def has_field?(field_name)
           raise NotImplementedError
         end

data/lib/dex/operation/record_wrapper.rb

@@ -5,6 +5,7 @@ module Dex
     extend Dex::Concern
 
     def _record_wrap
+      _record_validate_backend! if _record_enabled? || _record_has_pending_record?
       interceptor = Operation::HaltInterceptor.new { yield }
 
       if _record_has_pending_record?
@@ -34,6 +35,14 @@ module Dex
             "record expects true, false, or nil, got: #{enabled.inspect}"
         end
       end
+
+      def _record_required_fields(async: false)
+        settings = settings_for(:record)
+        fields = %w[name status performed_at error_code error_message error_details]
+        fields << "params" if async || settings.fetch(:params, true)
+        fields << "result" if settings.fetch(:result, true)
+        fields
+      end
     end
 
     private
@@ -46,6 +55,13 @@ module Dex
       record_settings.fetch(:enabled, true)
     end
 
+    def _record_validate_backend!(async: false)
+      Dex.record_backend.ensure_fields!(
+        self.class.send(:_record_required_fields, async: async),
+        feature: async ? "async recording" : "operation recording"
+      )
+    end
+
     def _record_has_pending_record?
       defined?(@_dex_record_id) && @_dex_record_id
     end
@@ -142,8 +158,8 @@ module Dex
       else
         case result
         when nil then nil
-        when Hash then result
-        else { _dex_value: result } # namespaced key so replay can distinguish wrapped primitives from user hashes
+        when Hash then _record_sanitize_value(result)
+        else { "_dex_value" => _record_sanitize_value(result) } # namespaced key so replay can distinguish wrapped primitives from user hashes
         end
       end
     end
@@ -160,10 +176,19 @@ module Dex
       case value
       when NilClass, String, Integer, Float, TrueClass, FalseClass then value
       when Symbol then value.to_s
-      when Hash then value.transform_values { |v| _record_sanitize_value(v) }
+      when Hash
+        value.each_with_object({}) do |(key, nested_value), result|
+          result[key.to_s] = _record_sanitize_value(nested_value)
+        end
       when Array then value.map { |v| _record_sanitize_value(v) }
       when Exception then "#{value.class}: #{value.message}"
-      else value.to_s
+      else
+        if value.respond_to?(:as_json)
+          serialized = value.as_json
+          return _record_sanitize_value(serialized) unless serialized.equal?(value)
+        end
+
+        value.to_s
       end
     end
 

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