dexkit 0.1.0

data/lib/dex/test_helpers/assertions.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module Dex
+  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
+
+    # --- 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

data/lib/dex/test_helpers/execution.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Dex
+  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

data/lib/dex/test_helpers/stubbing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Dex
+  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::TestWrapper.register_stub(klass, **opts)
+      yield
+    ensure
+      Dex::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

data/lib/dex/test_helpers.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative "test_log"
+
+module Dex
+  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::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
+    def self.included(base)
+      Dex::TestWrapper.install!
+      base.extend(ClassMethods)
+    end
+
+    def setup
+      super
+      Dex::TestLog.clear!
+      Dex::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
+
+require_relative "test_helpers/execution"
+require_relative "test_helpers/assertions"
+require_relative "test_helpers/stubbing"

data/lib/dex/test_log.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Dex
+  module TestLog
+    Entry = Data.define(:type, :name, :operation_class, :params, :result, :duration, :caller_location)
+
+    @_entries = []
+    @_mutex = Mutex.new
+
+    class << self
+      def record(entry)
+        @_mutex.synchronize { @_entries << entry }
+      end
+
+      def calls
+        @_mutex.synchronize { @_entries.dup }
+      end
+
+      def clear!
+        @_mutex.synchronize { @_entries.clear }
+      end
+
+      def size
+        @_mutex.synchronize { @_entries.size }
+      end
+
+      def empty?
+        @_mutex.synchronize { @_entries.empty? }
+      end
+
+      def find(klass, **params)
+        @_mutex.synchronize do
+          @_entries.select do |entry|
+            next false unless entry.operation_class == klass
+            params.all? { |k, v| entry.params[k] == v }
+          end
+        end
+      end
+
+      def summary
+        entries = calls
+        return "No operations called." if entries.empty?
+
+        lines = ["Operations called (#{entries.size}):"]
+        entries.each_with_index do |entry, i|
+          status = entry.result.ok? ? "OK" : "ERR(#{entry.result.code})"
+          duration_ms = entry.duration ? format("%.1fms", entry.duration * 1000) : "n/a"
+          lines << "  #{i + 1}. #{entry.name} [#{status}] #{duration_ms}"
+          lines << "     params: #{entry.params.inspect}" unless entry.params.nil? || entry.params.empty?
+        end
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/dex/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Dex
+  VERSION = "0.1.0"
+end

data/lib/dexkit.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+require "literal"
+require "time"
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/dex")
+loader.setup
+
+require_relative "dex/version"
+require_relative "dex/ref_type"
+require_relative "dex/error"
+require_relative "dex/operation"
+
+module Dex
+  class Configuration
+    attr_accessor :record_class, :transaction_adapter
+
+    def initialize
+      @record_class = nil
+      @transaction_adapter = nil
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def record_class
+      configuration.record_class
+    end
+
+    def record_backend
+      return @record_backend if defined?(@record_backend)
+      @record_backend = Operation::RecordBackend.for(record_class)
+    end
+
+    def reset_record_backend!
+      remove_instance_variable(:@record_backend) if defined?(@record_backend)
+    end
+
+    def transaction_adapter
+      configuration.transaction_adapter
+    end
+
+    def transaction_adapter=(adapter)
+      configuration.transaction_adapter = adapter
+    end
+  end
+end