model_timeline 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a6a1184662cefc583a463199b9ba93d0962f3c3c4d6fbcf2940074f0d508c71
-  data.tar.gz: 2380ec1607093282a3de23d9d20760ff4a09db115b1f84dc572cc8a57af5ac49
+  metadata.gz: 9d1c5aacdbe6970e7724f4f40d81c2e67b0f7739b7efe4784adb773a88d142a4
+  data.tar.gz: 38fc7b5502adf1a18809f8fd7aa54d3f5906888a9e37ed3f6b8fa9ef232e893c
 SHA512:
-  metadata.gz: 92139b98feed631b10c0cf102c0e702f9c8e901f9dfa3d769487c45611c95ceb22271233032d05e78d91fb23417d56e42e5571bcab46ee10c3dedd201c89a12f
-  data.tar.gz: d69052dbea970f0edade2611df282db871087ac850ccabce1f0aa56888d86fed35e8c399f603578cd364fbc5ce11fb8b69c6eb0ff9df7891fb6640a482fa0d97
+  metadata.gz: 5710fbe04cd8871236b90891e2298098b4d986b9d63e4f0c5943af5592b0e4ee47bf248490f2f508992a3a39ea50f20839f11d5b043196cbb8e6a527925d6d1c
+  data.tar.gz: 584e6aeb8875bffd927d86532e0b05cb2989027df80b6b5cf0ed15d587bfdce1f65f9f5cb6a92b8a88dc7e416ac56c653604d6f9635a6dc91a53ab4f97046192

data/README.md

@@ -385,11 +385,6 @@ Configure RSpec to work with ModelTimeline:
 require 'model_timeline/rspec'
 
 RSpec.configure do |config|
-  # This disables ModelTimeline by default in tests for better performance
-  config.before(:suite) do
-    ModelTimeline.disable!
-  end
-
   # Include the RSpec helpers and matchers
   config.include ModelTimeline::RSpec
 end
@@ -440,17 +435,65 @@ expect(user).to have_timeline_entries
 expect(user).to have_timeline_entries(3)
 
 # Check for entries with a specific action
-expect(user).to have_timelined_action(:update)
+expect(user).to have_timeline_entry_action(:update)
 
 # Check if a specific attribute was changed
-expect(user).to have_timelined_change(:email)
+expect(user).to have_timeline_entry_change(:email)
 
 # Check if an attribute was changed to a specific value
-expect(user).to have_timelined_entry(:status, 'active')
+expect(user).to have_timeline_entry(:status, 'active')
+
+# Check if an entry was created with expected metadata
+expect(user).to have_timeline_entry_metadata(foo: 'bar', baz: 'biz')
 ```
 
 These matchers make it easy to test that your application is correctly tracking model changes.
 
+##### Matchers for custom models/tables
+
+You can add a configuration in your support file to create matchers for your association.
+Given a model like this:
+
+```ruby
+class User < ApplicationRecord
+  has_timeline :security_events, class_name: 'SecurityTimelineEntry'
+end
+```
+
+You should set a configuration in your RSpec support file with:
+```ruby
+# spec/support/model_timeline.rb
+require 'model_timeline/rspec'
+
+RSpec.configure do |config|
+  # Include the RSpec helpers and matchers
+  config.include ModelTimeline::RSpec
+  config.include ModelTimeline::RSpec::Matchers.define_timeline_matchers_for(:security_events)
+end
+```
+
+Then you have those new matchers:
+
+```ruby
+# Check for any timeline entries
+expect(user).to have_security_events
+
+# Check for a specific number of entries
+expect(user).to have_security_events(3)
+
+# Check for entries with a specific action
+expect(user).to have_security_event_action(:update)
+
+# Check if a specific attribute was changed
+expect(user).to have_security_event_change(:email)
+
+# Check if an attribute was changed to a specific value
+expect(user).to have_security_event(:status, 'active')
+
+# Check if an entry was created with expected metadata
+expect(user).to have_security_event_metadata(foo: 'bar', baz: 'biz')
+```
+
 
 ## License
 

data/lib/model_timeline/rspec/matchers.rb

@@ -2,7 +2,6 @@
 
 module ModelTimeline
   module RSpec
-    # rubocop:disable Naming/PredicateName
     # Custom RSpec matchers for testing model timeline entries
     #
     # These matchers help you test the timeline entries created by the ModelTimeline gem.
@@ -16,58 +15,78 @@ module ModelTimeline
     #   expect(user).to have_timeline_entries(3)
     #
     #   # Check for specific action
-    #   expect(user).to have_timelined_action(:update)
+    #   expect(user).to have_timeline_entry_action(:update)
     #
     #   # Check for changes to a specific attribute
-    #   expect(user).to have_timelined_change(:email)
+    #   expect(user).to have_timeline_entry_change(:email)
     #
     #   # Check for specific value change
-    #   expect(user).to have_timelined_entry(:status, "active")
+    #   expect(user).to have_timeline_entry(:status, "active")
     module Matchers
-      # Check if a model has timeline entries
-      #
-      # @param count [Integer, nil] The expected number of timeline entries (optional)
-      # @return [HaveTimelineEntriesMatcher] A matcher that checks for timeline entries
-      # @example Without count parameter
-      #   expect(user).to have_timeline_entries
-      # @example With count parameter
-      #   expect(user).to have_timeline_entries(3)
-      def have_timeline_entries(count = nil)
-        HaveTimelineEntriesMatcher.new(count)
+      def self.included(base)
+        base.include define_timeline_matchers_for(:timeline_entries)
       end
 
-      # Check if a specific action was recorded in the timeline
-      #
-      # @param action [String, Symbol] The action name to look for
-      # @return [HaveTimelinedAction] A matcher that checks for a specific action
-      # @example
-      #   expect(user).to have_timelined_action(:create)
-      #   expect(user).to have_timelined_action("update")
-      def have_timelined_action(action)
-        HaveTimelinedAction.new(action)
-      end
+      def self.define_timeline_matchers_for(association_name)
+        association_name_singularized = association_name.to_s.singularize
 
-      # Check if a specific attribute change was recorded in the timeline
-      #
-      # @param attribute [String, Symbol] The attribute name to check for changes
-      # @return [HaveTimelinedChange] A matcher that checks if an attribute was changed
-      # @example
-      #   expect(user).to have_timelined_change(:email)
-      #   expect(user).to have_timelined_change("status")
-      def have_timelined_change(attribute)
-        HaveTimelinedChange.new(attribute)
-      end
+        Module.new do
+          # Check if a model has timeline entries
+          #
+          # @param count [Integer, nil] The expected number of timeline entries (optional)
+          # @return [HaveTimelineEntriesMatcher] A matcher that checks for timeline entries
+          # @example Without count parameter
+          #   expect(user).to have_timeline_entries
+          # @example With count parameter
+          #   expect(user).to have_timeline_entries(3)
+          define_method(:"have_#{association_name}") do |count = nil|
+            HaveTimelineEntriesMatcher.new(count, association_name)
+          end
 
-      # Check if an attribute was changed to a specific value in the timeline
-      #
-      # @param attribute [String, Symbol] The attribute name to check
-      # @param value [Object] The value to check for
-      # @return [HaveTimelinedEntry] A matcher that checks for specific attribute values
-      # @example
-      #   expect(user).to have_timelined_entry(:status, "active")
-      #   expect(user).to have_timelined_entry(:role, :admin)
-      def have_timelined_entry(attribute, value)
-        HaveTimelinedEntry.new(attribute, value)
+          # Check if a specific action was recorded in the timeline
+          #
+          # @param action [String, Symbol] The action name to look for
+          # @return [HaveTimelineAction] A matcher that checks for a specific action
+          # @example
+          #   expect(user).to have_timeline_entry_action(:create)
+          #   expect(user).to have_timeline_entry_action("update")
+          define_method(:"have_#{association_name_singularized}_action") do |action|
+            HaveTimelineAction.new(action, association_name)
+          end
+
+          # Check if a specific attribute change was recorded in the timeline
+          #
+          # @param attribute [String, Symbol] The attribute name to check for changes
+          # @return [HaveTimelineChange] A matcher that checks if an attribute was changed
+          # @example
+          #   expect(user).to have_timeline_entry_change(:email)
+          #   expect(user).to have_timeline_entry_change("status")
+          define_method(:"have_#{association_name_singularized}_change") do |attribute|
+            HaveTimelineChange.new(attribute, association_name)
+          end
+
+          # Check if an attribute was changed to a specific value in the timeline
+          #
+          # @param attribute [String, Symbol] The attribute name to check
+          # @param value [Object] The value to check for
+          # @return [HaveTimelineEntry] A matcher that checks for specific attribute values
+          # @example
+          #   expect(user).to have_timeline_entry(:status, "active")
+          #   expect(user).to have_timeline_entry(:role, :admin)
+          define_method(:"have_#{association_name_singularized}") do |attribute, value|
+            HaveTimelineEntry.new(attribute, value, association_name)
+          end
+
+          # Check if a model has timeline entries with specific metadata
+          #
+          # @param expected_metadata [Hash] The metadata key-value pairs to check for
+          # @return [HaveTimelineEntryMetadata] A matcher that checks for specific metadata
+          # @example
+          #   expect(user).to have_timeline_entry_metadata(foo: 'bar', baz: 'biz')
+          define_method(:"have_#{association_name_singularized}_metadata") do |expected_metadata|
+            HaveTimelineEntryMetadata.new(expected_metadata, association_name)
+          end
+        end
       end
 
       # RSpec matcher to check if a model has timeline entries
@@ -77,8 +96,9 @@ module ModelTimeline
         # Initialize the matcher
         #
         # @param expected_count [Integer, nil] The expected number of timeline entries
-        def initialize(expected_count)
+        def initialize(expected_count, association_name)
           @expected_count = expected_count
+          @association_name = association_name
         end
 
         # Check if the subject matches the expectations
@@ -88,9 +108,9 @@ module ModelTimeline
         def matches?(subject)
           @subject = subject
           if @expected_count.nil?
-            subject.timeline_entries.any?
+            subject.public_send(@association_name).any?
           else
-            subject.timeline_entries.count == @expected_count
+            subject.public_send(@association_name).count == @expected_count
           end
         end
 
@@ -102,7 +122,7 @@ module ModelTimeline
             "expected #{@subject} to have timeline entries, but found none"
           else
             "expected #{@subject} to have #{@expected_count} timeline entries, " \
-              "but found #{@subject.timeline_entries.count}"
+              "but found #{@subject.public_send(@association_name).count}"
           end
         end
 
@@ -111,7 +131,7 @@ module ModelTimeline
         # @return [String] A descriptive failure message for negated expectations
         def failure_message_when_negated
           if @expected_count.nil?
-            "expected #{@subject} not to have any timeline entries, but found #{@subject.timeline_entries.count}"
+            "expected #{@subject} not to have any timeline entries, but found #{@subject.public_send(@association_name).count}"
           else
             "expected #{@subject} not to have #{@expected_count} timeline entries, but found exactly that many"
           end
@@ -121,12 +141,13 @@ module ModelTimeline
       # RSpec matcher to check if a model has timeline entries with a specific action
       #
       # @api private
-      class HaveTimelinedAction
+      class HaveTimelineAction
         # Initialize the matcher
         #
         # @param action [String, Symbol] The action to look for
-        def initialize(action)
+        def initialize(action, association_name)
           @action = action.to_s
+          @association_name = association_name
         end
 
         # Check if the subject matches the expectations
@@ -135,7 +156,7 @@ module ModelTimeline
         # @return [Boolean] True if the model has timeline entries with the specified action
         def matches?(subject)
           @subject = subject
-          subject.timeline_entries.where(action: @action).exists?
+          @subject.public_send(@association_name).where(action: @action).exists?
         end
 
         # Message displayed when the expectation fails
@@ -156,12 +177,13 @@ module ModelTimeline
       # RSpec matcher to check if a model has timeline entries with changes to a specific attribute
       #
       # @api private
-      class HaveTimelinedChange
+      class HaveTimelineChange
         # Initialize the matcher
         #
         # @param attribute [String, Symbol] The attribute to check for changes
-        def initialize(attribute)
+        def initialize(attribute, association_name)
           @attribute = attribute.to_s
+          @association_name = association_name
         end
 
         # Check if the subject matches the expectations
@@ -170,7 +192,7 @@ module ModelTimeline
         # @return [Boolean] True if the model has timeline entries with changes to the specified attribute
         def matches?(subject)
           @subject = subject
-          subject.timeline_entries.with_changed_attribute(@attribute).exists?
+          @subject.public_send(@association_name).with_changed_attribute(@attribute).exists?
         end
 
         # Message displayed when the expectation fails
@@ -191,14 +213,15 @@ module ModelTimeline
       # RSpec matcher to check if a model has timeline entries where an attribute changed to a specific value
       #
       # @api private
-      class HaveTimelinedEntry
+      class HaveTimelineEntry
         # Initialize the matcher
         #
         # @param attribute [String, Symbol] The attribute to check
         # @param value [Object] The value the attribute should have changed to
-        def initialize(attribute, value)
+        def initialize(attribute, value, association_name)
           @attribute = attribute.to_s
           @value = value
+          @association_name = association_name
         end
 
         # Check if the subject matches the expectations
@@ -207,7 +230,7 @@ module ModelTimeline
         # @return [Boolean] True if the model has timeline entries where the attribute changed to the specified value
         def matches?(subject)
           @subject = subject
-          subject.timeline_entries.with_changed_value(@attribute, @value).exists?
+          @subject.public_send(@association_name).with_changed_value(@attribute, @value).exists?
         end
 
         # Message displayed when the expectation fails
@@ -224,7 +247,52 @@ module ModelTimeline
           "expected #{@subject} not to have tracked '#{@attribute}' changing to '#{@value}', but such a change was found"
         end
       end
+
+      # RSpec matcher to check if a model has timeline entries with specific metadata
+      #
+      # @api private
+      class HaveTimelineEntryMetadata
+        # Initialize the matcher
+        #
+        # @param expected_metadata [Hash] The metadata key-value pairs to check for
+        # @param association_name [Symbol] The name of the timeline association
+        def initialize(expected_metadata, association_name)
+          @expected_metadata = expected_metadata
+          @association_name = association_name
+        end
+
+        # Check if the subject matches the expectations
+        #
+        # @param subject [Object] The model to check for timeline entries
+        # @return [Boolean] True if the model has timeline entries with the specified metadata
+        def matches?(subject)
+          @subject = subject
+
+          # Build a query that checks for each key-value pair in the metadata
+          entries = subject.public_send(@association_name)
+
+          # Construct queries for each metadata key-value pair
+          @expected_metadata.all? do |key, value|
+            # Use a JSON containment query to check if the metadata contains the key-value pair
+            # This syntax works with PostgreSQL's JSONB containment operator @>
+            entries.where('metadata @> ?', { key.to_s => value }.to_json).exists?
+          end
+        end
+
+        # Message displayed when the expectation fails
+        #
+        # @return [String] A descriptive failure message
+        def failure_message
+          "expected #{@subject} to have timeline entries with metadata #{@expected_metadata.inspect}, but none was found"
+        end
+
+        # Message displayed when the negated expectation fails
+        #
+        # @return [String] A descriptive failure message for negated expectations
+        def failure_message_when_negated
+          "expected #{@subject} not to have timeline entries with metadata #{@expected_metadata.inspect}, but such entries were found"
+        end
+      end
     end
-    # rubocop:enable Naming/PredicateName
   end
 end

data/lib/model_timeline/rspec.rb

@@ -20,7 +20,7 @@ module ModelTimeline
   #   describe User, :with_timeline do
   #     it "records timeline entries when updated" do
   #       user.update(name: "New Name")
-  #       expect(user).to have_timelined_change(:name)
+  #       expect(user).to have_timeline_entry_change(:name)
   #     end
   #   end
   module RSpec

data/lib/model_timeline/timelineable.rb

@@ -185,8 +185,7 @@ module ModelTimeline
 
       # Collects metadata for the timeline entry
       #
-      # @param meta_config [Hash] The metadata configuration
-      # @param config_key [String] The configuration key for this model
+      # @param meta_config [Hash, Proc] The metadata configuration
       # @return [Hash] Collected metadata
       def collect_metadata(meta_config)
         metadata = {}
@@ -194,22 +193,46 @@ module ModelTimeline
         # First, add any thread-level metadata
         metadata.merge!(ModelTimeline.metadata)
 
-        # Then, add any model-specific metadata defined in config
-        meta_config.each do |key, value|
-          resolved_value = case value
-                           when Proc
-                             instance_exec(self, &value)
-                           when Symbol
-                             respond_to?(value) ? send(value) : value
-                           else
-                             value
-                           end
-          metadata[key] = resolved_value
-        end
+        # Then, add any model-specific metadata from config
+        metadata.merge!(resolve_metadata_value(meta_config))
 
         metadata
       end
 
+      # Recursively resolves metadata values
+      #
+      # @param value [Hash, Proc, Symbol, Object] The value to resolve
+      # @return [Hash, Object] The resolved value
+      def resolve_metadata_value(value)
+        case value
+        when Proc
+          # If it's a Proc, execute it and process the result recursively
+          proc_result = instance_exec(self, &value)
+          proc_result.is_a?(Hash) ? process_metadata_hash(proc_result) : proc_result
+        when Hash
+          # If it's a Hash, process each key-value pair
+          process_metadata_hash(value)
+        when Symbol
+          # If it's a Symbol, try to call the method
+          respond_to?(value) ? send(value) : value
+        else
+          # Any other value, return as-is
+          value
+        end
+      end
+
+      # Processes a metadata hash by resolving each value
+      #
+      # @param hash [Hash] The hash to process
+      # @return [Hash] The processed hash
+      def process_metadata_hash(hash)
+        result = {}
+        hash.each do |key, val|
+          result[key] = resolve_metadata_value(val)
+        end
+        result
+      end
+
       def column_metadata(config)
         metadata = collect_metadata(config[:meta])
         column_names = config[:klass].column_names.map(&:to_sym)

data/lib/model_timeline/version.rb

@@ -5,5 +5,5 @@ module ModelTimeline
   # Follows semantic versioning (https://semver.org/).
   #
   # @return [String] The current version in the format "MAJOR.MINOR.PATCH"
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: model_timeline
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Alexandre Stapenhorst
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-03 00:00:00.000000000 Z
+date: 2025-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg