tapping_device 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b44a9cf6d9eb0e17b965c87b38f5c431058c283c2a6b79dcce1d2b88aafcc5e
-  data.tar.gz: 6afad055a9606958c47534cfa68394bc859c465300ac2c3f9959335edc0b7f4d
+  metadata.gz: fbf652959b6f125f5e4ece39c59db0b8ebd55096e4aa639452de306857193bf7
+  data.tar.gz: 31d13f1f4f38b6009795e4d948ba4596428355cb03d113603b3801c307c14a18
 SHA512:
-  metadata.gz: e36715dc9d885af5b143ace2b5c3af6ff782e49d371e4b24787ac475f58d140abbad1a9730769722a59c2e06240a3a72930d9588f488595eaa6dc75973a17a31
-  data.tar.gz: e3bd4a46af607281dc82e6bb4e3f57ad54f600d99a25892d7914c4e5577dcf8a3dc212d60449e9ced5b1789680eead0f79f3758ef6b06c25b1b7647f52e2282e
+  metadata.gz: 98eae30679e7e08f7607dbd7ee457b9db9565e46ddf2859a782f2b5ce817bf014937b65f8ee0f342bb7d6dbec3afcb3aef980e396362726839c4031db03cb2e5
+  data.tar.gz: bf2d0e6e8e38466f928d57580edf745b1ee1ce18ed1ee03968dc76647b67cfb4e0feaeff0166ac7503c295c54351445344f828a0bc3878b57a74ed8a130a03cb

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    tapping_device (0.5.1)
+    tapping_device (0.5.2)
       activerecord (>= 5.2)
+      pry
 
 GEM
   remote: https://rubygems.org/
@@ -18,7 +19,7 @@ GEM
       minitest (~> 5.1)
       tzinfo (~> 1.1)
       zeitwerk (~> 2.2, >= 2.2.2)
-    coderay (1.1.2)
+    coderay (1.1.3)
     concurrent-ruby (1.1.6)
     database_cleaner (1.7.0)
     diff-lcs (1.3)
@@ -26,11 +27,11 @@ GEM
     i18n (1.8.3)
       concurrent-ruby (~> 1.0)
     json (2.3.0)
-    method_source (0.9.2)
+    method_source (1.0.0)
     minitest (5.14.1)
-    pry (0.12.2)
-      coderay (~> 1.1.0)
-      method_source (~> 0.9.0)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
     rake (13.0.1)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
@@ -62,7 +63,6 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 2.0)
   database_cleaner
-  pry
   rake (~> 13.0)
   rspec (~> 3.0)
   simplecov (= 0.17.1)

data/README.md

@@ -10,16 +10,17 @@
 ## Introduction
 `TappingDevice` makes the objects tell you what they do, so you don't need to track them yourself.
 
-#### Contract Tracing For Objects
+#### Contact Tracing For Objects
 
 The concept is very simple. It's basically like [contact tracing](https://en.wikipedia.org/wiki/Contact_tracing) for your Ruby objects. You can use 
 
 - `print_calls(object)` to see what the object does
 - `print_traces(object)` to see how the object interacts with other objects (like used as an argument)
+- `print_mutations(object)` to see what actions changed the object's state (instance variables)
 
 Still sounds vague? Let's see some examples:
 
-### `print_calls` To Track Method Calls
+### `print_calls` - Track Method Calls
 
 In [Discourse](https://github.com/discourse/discourse), it uses the `Guardian` class for authorization (like policy objects). It's barely visible in controller actions, but it does many checks under the hood. Now, let's say we want to know what the `Guardian` would do when a user creates a post; here's the controller action:
 
@@ -81,7 +82,7 @@ Let's take a closer look at each entry. Everyone of them contains the method cal
 These are the information you'd have to look up one by one manually (probably with many debug code writing). Now you can get all of them in just one line of code.
 
 
-### `print_traces` To See The Object's Traces
+### `print_traces` - See The Object's Traces
 
 If you're not interested in what an object does, but what it interacts with other parts of the program, e.g., used as arguments. You can use the `print_traces` helper. Let's see how `Discourse` uses the `manager` object when creating a post
 
@@ -106,6 +107,71 @@ You will see that it performs 2 calls: `perform` and `perform_create_post`. And
 
 ![image of print_traces output](https://github.com/st0012/tapping_device/blob/master/images/print_traces.png)
 
+### `print_mutations` - Display All State Changes At Once
+
+Another thing that often bothers developers in debugging is to track an object's internal state changes. And `tapping_device` allows you to see all state changes with just one line of code. Let me keep using [Discourse](https://github.com/discourse/discourse) to demonstrate it. 
+
+When updating a post, it uses an object called `PostRevisor` to revise it:
+
+```ruby
+# app/controllers/posts_controller.rb
+class PostsController
+  def update
+    # ......
+    revisor = PostRevisor.new(post, topic)
+    revisor.revise!(current_user, changes, opts)
+    # ......
+  end
+end
+```
+
+In the `PostReviser#revise!`, it uses many instance variables to track different information:
+
+```ruby
+  # lib/post_revisor.rb
+  def revise!(editor, fields, opts = {})
+    @editor = editor
+    @fields = fields.with_indifferent_access
+    @opts = opts
+
+    @topic_changes = TopicChanges.new(@topic, editor)
+    
+    # ......
+
+    @revised_at = @opts[:revised_at] || Time.now
+    @last_version_at = @post.last_version_at || Time.now
+
+    @version_changed = false
+    @post_successfully_saved = true
+
+    @validate_post = true
+    # ......
+  end
+```
+
+Tracking the changes of that many instance variables can be a painful task, especially when we want to know the values before and after certain method call. This is why I created `print_mutations` to save us from this. 
+
+Like other helpers, you only need 1 line of code
+
+```ruby
+# app/controllers/posts_controller.rb
+class PostsController
+  def update
+    # ......
+    revisor = PostRevisor.new(post, topic)
+    print_mutations(revisor)
+    revisor.revise!(current_user, changes, opts)
+    # ......
+  end
+end
+```
+
+And then you'll see all the state changes:
+
+<img src="https://github.com/st0012/tapping_device/blob/master/images/print_mutations.png" alt="image of print_mutations output" width="50%">
+
+Now you can see what method changes which states. And more importantly, you get to see all the sate changes at once!
+
 **You can try these examples on [my fork of discourse](https://github.com/st0012/discourse/tree/demo-for-tapping-device)**
 
 
@@ -190,3 +256,4 @@ The gem is available as open-source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the TappingDevice project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/tapping_device/blob/master/CODE_OF_CONDUCT.md).
+

data/lib/tapping_device.rb

@@ -5,6 +5,11 @@ require "tapping_device/payload"
 require "tapping_device/output_payload"
 require "tapping_device/trackable"
 require "tapping_device/exceptions"
+require "tapping_device/trackers/initialization_tracker"
+require "tapping_device/trackers/passed_tracker"
+require "tapping_device/trackers/association_call_tracker"
+require "tapping_device/trackers/method_call_tracker"
+require "tapping_device/trackers/mutation_tracker"
 
 class TappingDevice
 
@@ -25,28 +30,7 @@ class TappingDevice
     @calls = []
     @disabled = false
     @with_condition = nil
-    self.class.devices << self
-  end
-
-  def tap_init!(klass)
-    raise "argument should be a class, got #{klass}" unless klass.is_a?(Class)
-    track(klass, condition: :tap_init?) do |payload|
-      payload[:return_value] = payload[:receiver]
-      payload[:receiver] = klass
-    end
-  end
-
-  def tap_on!(object)
-    track(object, condition: :tap_on?)
-  end
-
-  def tap_passed!(object)
-    track(object, condition: :tap_passed?)
-  end
-
-  def tap_assoc!(record)
-    raise "argument should be an instance of ActiveRecord::Base" unless record.is_a?(ActiveRecord::Base)
-    track(record, condition: :tap_associations?)
+    TappingDevice.devices << self
   end
 
   def and_print(payload_method = nil, &block)
@@ -72,7 +56,7 @@ class TappingDevice
 
   def stop!
     @disabled = true
-    self.class.delete_device(self)
+    TappingDevice.delete_device(self)
   end
 
   def stop_when(&block)
@@ -95,67 +79,68 @@ class TappingDevice
     options[:descendants]
   end
 
-  private
-
-  def track(object, condition:, &payload_block)
+  def track(object)
     @target = object
-    @trace_point = TracePoint.new(options[:event_type]) do |tp|
-      if send(condition, object, tp)
-        filepath, line_number = get_call_location(tp)
+    validate_target!
+
+    @trace_point = build_minimum_trace_point(event_type: options[:event_type]) do |payload|
+      record_call!(payload)
 
-        next if should_be_skipped_by_paths?(filepath)
+      stop_if_condition_fulfilled!(payload)
+    end
+
+    @trace_point.enable unless TappingDevice.suspend_new
 
-        payload = build_payload(tp: tp, filepath: filepath, line_number: line_number, &payload_block)
+    self
+  end
 
-        next unless with_condition_satisfied?(payload)
+  private
 
-        # skip TappingDevice related calls
-        if Module.respond_to?(:module_parents)
-          next if payload.defined_class.module_parents.include?(TappingDevice)
-        else
-          next if payload.defined_class.parents.include?(TappingDevice)
-        end
+  def build_minimum_trace_point(event_type:)
+    TracePoint.new(event_type) do |tp|
+      next unless filter_condition_satisfied?(tp)
+      next if is_tapping_device_call?(tp)
 
-        record_call!(payload)
+      filepath, line_number = get_call_location(tp)
+      payload = build_payload(tp: tp, filepath: filepath, line_number: line_number)
 
-        stop_if_condition_fulfilled(payload)
-      end
+      next if should_be_skipped_by_paths?(filepath)
+      next unless with_condition_satisfied?(payload)
+
+      yield(payload)
     end
+  end
 
-    @trace_point.enable unless self.class.suspend_new
+  def validate_target!; end
 
-    self
+  def filter_condition_satisfied?(tp)
+    false
   end
 
-  def get_call_location(tp, padding: 0)
-    caller(get_trace_index(tp) + padding).first.split(":")[0..1]
+  # this needs to be placed upfront so we can exclude noise before doing more work
+  def should_be_skipped_by_paths?(filepath)
+    options[:exclude_by_paths].any? { |pattern| pattern.match?(filepath) } ||
+      (options[:filter_by_paths].present? && !options[:filter_by_paths].any? { |pattern| pattern.match?(filepath) })
   end
 
-  def get_trace_index(tp)
-    if tp.event == :c_call
-      C_CALLER_START_POINT
-    else
-      CALLER_START_POINT
+  def is_tapping_device_call?(tp)
+    if tp.defined_class == TappingDevice::Trackable || tp.defined_class == TappingDevice
+      return true
     end
-  end
 
-  def get_traces(tp)
-    if with_trace_to = options[:with_trace_to]
-      trace_index = get_trace_index(tp)
-      caller[trace_index..(trace_index + with_trace_to)]
+    if Module.respond_to?(:module_parents)
+      tp.defined_class.module_parents.include?(TappingDevice)
     else
-      []
+      tp.defined_class.parents.include?(TappingDevice)
     end
   end
 
-  # this needs to be placed upfront so we can exclude noise before doing more work
-  def should_be_skipped_by_paths?(filepath)
-    options[:exclude_by_paths].any? { |pattern| pattern.match?(filepath) } ||
-      (options[:filter_by_paths].present? && !options[:filter_by_paths].any? { |pattern| pattern.match?(filepath) })
+  def with_condition_satisfied?(payload)
+    @with_condition.blank? || @with_condition.call(payload)
   end
 
   def build_payload(tp:, filepath:, line_number:)
-    payload = Payload.init({
+    Payload.init({
       target: @target,
       receiver: tp.self,
       method_name: tp.callee_id,
@@ -168,47 +153,6 @@ class TappingDevice
       trace: get_traces(tp),
       tp: tp
     })
-
-    yield(payload) if block_given?
-
-    payload
-  end
-
-  def tap_init?(klass, tp)
-    receiver = tp.self
-    method_name = tp.callee_id
-
-    if klass.ancestors.include?(ActiveRecord::Base)
-      method_name == :new && receiver.ancestors.include?(klass)
-    else
-      method_name == :initialize && receiver.is_a?(klass)
-    end
-  end
-
-  def tap_on?(object, tp)
-    is_from_target?(object, tp)
-  end
-
-  def tap_associations?(object, tp)
-    return false unless tap_on?(object, tp)
-
-    model_class = object.class
-    associations = model_class.reflections
-    associations.keys.include?(tp.callee_id.to_s)
-  end
-
-  def tap_passed?(object, tp)
-    # we don't care about calls from the device instance or helper methods
-    return false if is_from_target?(self, tp)
-    return false if tp.defined_class == TappingDevice::Trackable || tp.defined_class == TappingDevice
-
-    collect_arguments(tp).values.any? do |value|
-      # during comparison, Ruby might perform data type conversion like calling `to_sym` on the value
-      # but not every value supports every conversion methods
-      object == value rescue false
-    end
-  rescue
-    false
   end
 
   def get_method_object_from(target, method_name)
@@ -222,6 +166,27 @@ class TappingDevice
     nil
   end
 
+  def get_call_location(tp, padding: 0)
+    caller(get_trace_index(tp) + padding).first.split(":")[0..1]
+  end
+
+  def get_trace_index(tp)
+    if tp.event == :c_call
+      C_CALLER_START_POINT
+    else
+      CALLER_START_POINT
+    end
+  end
+
+  def get_traces(tp)
+    if with_trace_to = options[:with_trace_to]
+      trace_index = get_trace_index(tp)
+      caller[trace_index..(trace_index + with_trace_to)]
+    else
+      []
+    end
+  end
+
   def collect_arguments(tp)
     parameters =
       if RUBY_VERSION.to_f >= 2.6
@@ -246,19 +211,12 @@ class TappingDevice
     options
   end
 
-  def stop_if_condition_fulfilled(payload)
-    if @stop_when&.call(payload)
-      stop!
-      root_device.stop!
-    end
-  end
-
-  def is_from_target?(object, tp)
+  def is_from_target?(tp)
     comparsion = tp.self
-    is_the_same_record?(object, comparsion) || object.__id__ == comparsion.__id__
+    is_the_same_record?(comparsion) || target.__id__ == comparsion.__id__
   end
 
-  def is_the_same_record?(target, comparsion)
+  def is_the_same_record?(comparsion)
     return false unless options[:track_as_records]
     if target.is_a?(ActiveRecord::Base) && comparsion.is_a?(target.class)
       primary_key = target.class.primary_key
@@ -278,7 +236,10 @@ class TappingDevice
     end
   end
 
-  def with_condition_satisfied?(payload)
-    @with_condition.blank? || @with_condition.call(payload)
+  def stop_if_condition_fulfilled!(payload)
+    if @stop_when&.call(payload)
+      stop!
+      root_device.stop!
+    end
   end
 end

data/lib/tapping_device/exceptions.rb

@@ -1,4 +1,16 @@
 class TappingDevice
   class Exception < StandardError
   end
+
+  class NotAnActiveRecordInstanceError < Exception
+    def initialize(object)
+      super("target object should be an instance of ActiveRecord::Base, got #{object}")
+    end
+  end
+
+  class NotAClassError < Exception
+    def initialize(object)
+      super("target object should be a class, got #{object}")
+    end
+  end
 end

data/lib/tapping_device/output_payload.rb

@@ -1,5 +1,7 @@
 class TappingDevice
   class OutputPayload < Payload
+    UNDEFINED = "[undefined]"
+
     alias :raw_arguments :arguments
     alias :raw_return_value :return_value
 
@@ -15,9 +17,6 @@ class TappingDevice
       generate_string_result(raw_return_value, options[:inspect])
     end
 
-    def self.full_color_code(code)
-    end
-
     COLOR_CODES = {
       green: 10,
       yellow: 11,
@@ -37,9 +36,9 @@ class TappingDevice
     PAYLOAD_ATTRIBUTES = {
       method_name: {symbol: "", color: COLORS[:blue]},
       location: {symbol: "from:", color: COLORS[:green]},
-      sql: {symbol: "QUERIES", color: COLORS[:nocolor]},
       return_value: {symbol: "=>", color: COLORS[:megenta]},
       arguments: {symbol: "<=", color: COLORS[:orange]},
+      ivar_changes: {symbol: "changes:\n", color: COLORS[:blue]},
       defined_class: {symbol: "#", color: COLORS[:yellow]}
     }
 
@@ -99,6 +98,31 @@ class TappingDevice
       MSG
     end
 
+    def ivar_changes(options = {})
+      super.map do |ivar, value_changes|
+        before = generate_string_result(value_changes[:before], options[:inspect])
+        after = generate_string_result(value_changes[:after], options[:inspect])
+
+        if options[:colorize]
+          ivar = "#{COLORS[:orange]}#{ivar}#{COLORS[:reset]}"
+          before = "#{COLORS[:blue]}#{before.to_s}#{COLORS[:reset]}"
+          after = "#{COLORS[:blue]}#{after.to_s}#{COLORS[:reset]}"
+        end
+
+        "      #{ivar}: #{before.to_s} => #{after.to_s}"
+      end.join("\n")
+    end
+
+    def call_info_with_ivar_changes(options = {})
+      <<~MSG
+      #{method_name_and_defined_class(options)}
+          from: #{location(options)}
+          changes:
+      #{ivar_changes(options)}
+
+      MSG
+    end
+
     private
 
     def value_with_color(value, color)
@@ -111,8 +135,12 @@ class TappingDevice
         array_to_string(obj, inspect)
       when Hash
         hash_to_string(obj, inspect)
+      when UNDEFINED
+        UNDEFINED
       when String
         "\"#{obj}\""
+      when nil
+        "nil"
       else
         inspect ? obj.inspect : obj.to_s
       end

data/lib/tapping_device/payload.rb

@@ -2,7 +2,7 @@ class TappingDevice
   class Payload < Hash
     ATTRS = [
       :target, :receiver, :method_name, :method_object, :arguments, :return_value, :filepath, :line_number,
-      :defined_class, :trace, :tp, :sql
+      :defined_class, :trace, :tp, :ivar_changes
     ]
 
     ATTRS.each do |attr|

data/lib/tapping_device/trackable.rb

@@ -1,36 +1,58 @@
 class TappingDevice
   module Trackable
-    [:tap_on!, :tap_init!, :tap_assoc!, :tap_passed!].each do |method|
-      define_method method do |object, options = {}, &block|
-        new_device(options, &block).send(method, object)
-      end
+    def tap_init!(object, options = {}, &block)
+      TappingDevice::Trackers::InitializationTracker.new(options, &block).track(object)
+    end
+
+    def tap_passed!(object, options = {}, &block)
+      TappingDevice::Trackers::PassedTracker.new(options, &block).track(object)
+    end
+
+    def tap_assoc!(object, options = {}, &block)
+      TappingDevice::Trackers::AssociactionCallTracker.new(options, &block).track(object)
+    end
+
+    def tap_on!(object, options = {}, &block)
+      TappingDevice::Trackers::MethodCallTracker.new(options, &block).track(object)
+    end
+
+    def tap_mutation!(object, options = {}, &block)
+      TappingDevice::Trackers::MutationTracker.new(options, &block).track(object)
     end
 
     def print_traces(target, options = {})
+      output_options = extract_output_options(options)
       options[:event_type] = :call
-      inspect = options.delete(:inspect)
-      colorize = options.fetch(:colorize, true)
 
       device_1 = tap_on!(target, options).and_print do |output_payload|
-        "Called #{output_payload.method_name_and_location(inspect: inspect, colorize: colorize)}"
+        "Called #{output_payload.method_name_and_location(output_options)}"
       end
       device_2 = tap_passed!(target, options).and_print do |output_payload|
-        output_payload.passed_at(inspect: inspect, colorize: colorize)
+        output_payload.passed_at(output_options)
       end
       CollectionProxy.new([device_1, device_2])
     end
 
     def print_calls(target, options = {})
-      inspect = options.delete(:inspect)
-      colorize = options.fetch(:colorize, true)
+      output_options = extract_output_options(options)
 
       tap_on!(target, options).and_print do |output_payload|
-        output_payload.detail_call_info(inspect: inspect, colorize: colorize)
+        output_payload.detail_call_info(output_options)
       end
     end
 
-    def new_device(options, &block)
-      TappingDevice.new(options, &block)
+    def print_mutations(target, options = {})
+      output_options = extract_output_options(options)
+
+      tap_mutation!(target, options).and_print do |output_payload|
+        output_payload.call_info_with_ivar_changes(output_options)
+      end
+    end
+
+    private
+
+    def extract_output_options(options)
+      {inspect: options.delete(:inspect), colorize: options.fetch(:colorize, true)}
     end
 
     class CollectionProxy

data/lib/tapping_device/trackers/association_call_tracker.rb

@@ -0,0 +1,17 @@
+class TappingDevice
+  module Trackers
+    class AssociactionCallTracker < TappingDevice
+      def validate_target!
+        raise NotAnActiveRecordInstanceError.new(target) unless target.is_a?(ActiveRecord::Base)
+      end
+
+      def filter_condition_satisfied?(tp)
+        return false unless is_from_target?(tp)
+
+        model_class = target.class
+        associations = model_class.reflections
+        associations.keys.include?(tp.callee_id.to_s)
+      end
+    end
+  end
+end

data/lib/tapping_device/trackers/initialization_tracker.rb

@@ -0,0 +1,27 @@
+class TappingDevice
+  module Trackers
+    class InitializationTracker < TappingDevice
+      def build_payload(tp:, filepath:, line_number:)
+        payload = super
+        payload[:return_value] = payload[:receiver]
+        payload[:receiver] = target
+        payload
+      end
+
+      def validate_target!
+        raise NotAClassError.new(target) unless target.is_a?(Class)
+      end
+
+      def filter_condition_satisfied?(tp)
+        receiver = tp.self
+        method_name = tp.callee_id
+
+        if target.ancestors.include?(ActiveRecord::Base)
+          method_name == :new && receiver.ancestors.include?(target)
+        else
+          method_name == :initialize && receiver.is_a?(target)
+        end
+      end
+    end
+  end
+end

data/lib/tapping_device/trackers/method_call_tracker.rb

@@ -0,0 +1,9 @@
+class TappingDevice
+  module Trackers
+    class MethodCallTracker < TappingDevice
+      def filter_condition_satisfied?(tp)
+        is_from_target?(tp)
+      end
+    end
+  end
+end

data/lib/tapping_device/trackers/mutation_tracker.rb

@@ -0,0 +1,132 @@
+require "pry" # for using Method#source
+
+class TappingDevice
+  module Trackers
+    class MutationTracker < TappingDevice
+      def initialize(options, &block)
+        super
+        @snapshot_stack = []
+      end
+
+      def track(object)
+        super
+        hijack_attr_writers
+        insert_snapshot_taking_trace_point
+        self
+      end
+
+      def stop!
+        super
+        @ivar_snapshot_trace_point.disable
+      end
+
+      private
+
+      # we need to snapshot instance variables at the beginning of every method call
+      # so we can get a correct state for the later comparison
+      def insert_snapshot_taking_trace_point
+        @ivar_snapshot_trace_point = build_minimum_trace_point(event_type: :call) do
+          snapshot_instance_variables
+        end
+
+        @ivar_snapshot_trace_point.enable unless TappingDevice.suspend_new
+      end
+
+      def filter_condition_satisfied?(tp)
+        return false unless is_from_target?(tp)
+
+        if snapshot_capturing_event?(tp)
+          true
+        else
+          @latest_instance_variables = target_instance_variables
+          @instance_variables_snapshot = @snapshot_stack.pop
+
+          @latest_instance_variables != @instance_variables_snapshot
+        end
+      end
+
+      def hijack_attr_writers
+        writer_methods = target.methods.grep(/\w+=/)
+        writer_methods.each do |method_name|
+          if target.method(method_name).source.match?(/attr_writer|attr_accessor/)
+            ivar_name = "@#{method_name.to_s.sub("=", "")}"
+
+            # need to use instance_eval to make the call site location consistent with normal methods
+            target.instance_eval(
+              <<~CODE
+                def #{method_name}(val)
+                  #{ivar_name} = val
+                end
+              CODE
+            )
+          end
+        end
+      end
+
+      def build_payload(tp:, filepath:, line_number:)
+        payload = super
+
+        if change_capturing_event?(tp)
+          payload[:ivar_changes] = capture_ivar_changes
+        end
+
+        payload
+      end
+
+      def capture_ivar_changes
+        changes = {}
+
+        additional_keys = @latest_instance_variables.keys - @instance_variables_snapshot.keys
+        additional_keys.each do |key|
+          changes[key] = {before: OutputPayload::UNDEFINED, after: @latest_instance_variables[key]}
+        end
+
+        removed_keys = @instance_variables_snapshot.keys - @latest_instance_variables.keys
+        removed_keys.each do |key|
+          changes[key] = {before: @instance_variables_snapshot[key], after: OutputPayload::UNDEFINED}
+        end
+
+        remained_keys = @latest_instance_variables.keys - additional_keys
+        remained_keys.each do |key|
+          next if @latest_instance_variables[key] == @instance_variables_snapshot[key]
+          changes[key] = {before: @instance_variables_snapshot[key], after: @latest_instance_variables[key]}
+        end
+
+        changes
+      end
+
+      def snapshot_instance_variables
+        @snapshot_stack.push(target_instance_variables)
+      end
+
+      def target_instance_variables
+        target.instance_variables.each_with_object({}) do |ivar, hash|
+          hash[ivar] = target.instance_variable_get(ivar)
+        end
+      end
+
+      def snapshot_capturing_event?(tp)
+        tp.event == :call
+      end
+
+      def change_capturing_event?(tp)
+        !snapshot_capturing_event?(tp)
+      end
+
+      # belows are debugging helpers
+      # I'll leave them for a while in case there's a bug in the tracker
+      def print_snapshot_stack(tp)
+        puts("===== STACK - #{tp.callee_id} (#{tp.event}) =====")
+        puts(@snapshot_stack)
+        puts("================ END STACK =================")
+      end
+
+      def print_state_comparison
+        puts("###############")
+        puts(@latest_instance_variables)
+        puts(@instance_variables_snapshot)
+        puts("###############")
+      end
+    end
+  end
+end

data/lib/tapping_device/trackers/passed_tracker.rb

@@ -0,0 +1,16 @@
+class TappingDevice
+  module Trackers
+    # PassedTracker tracks calls that use the target object as an argument
+    class PassedTracker < TappingDevice
+      def filter_condition_satisfied?(tp)
+        collect_arguments(tp).values.any? do |value|
+          # during comparison, Ruby might perform data type conversion like calling `to_sym` on the value
+          # but not every value supports every conversion methods
+          target == value rescue false
+        end
+      rescue
+        false
+      end
+    end
+  end
+end

data/lib/tapping_device/version.rb

@@ -1,3 +1,3 @@
 class TappingDevice
-  VERSION = "0.5.1"
+  VERSION = "0.5.2"
 end

data/tapping_device.gemspec

@@ -32,10 +32,11 @@ Gem::Specification.new do |spec|
     spec.add_dependency "activerecord", ">= 5.2"
   end
 
+  spec.add_dependency "pry" # for using Method#source in MutationTracker
+
   spec.add_development_dependency "sqlite3", ">= 1.3.6"
   spec.add_development_dependency "database_cleaner"
   spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "pry"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "simplecov", "0.17.1"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tapping_device
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.2
 platform: ruby
 authors:
 - st0012
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-06-07 00:00:00.000000000 Z
+date: 2020-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -66,20 +80,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: pry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -147,6 +147,7 @@ files:
 - bin/setup
 - images/print_calls - single entry.png
 - images/print_calls.png
+- images/print_mutations.png
 - images/print_traces.png
 - lib/tapping_device.rb
 - lib/tapping_device/exceptions.rb
@@ -154,6 +155,11 @@ files:
 - lib/tapping_device/output_payload.rb
 - lib/tapping_device/payload.rb
 - lib/tapping_device/trackable.rb
+- lib/tapping_device/trackers/association_call_tracker.rb
+- lib/tapping_device/trackers/initialization_tracker.rb
+- lib/tapping_device/trackers/method_call_tracker.rb
+- lib/tapping_device/trackers/mutation_tracker.rb
+- lib/tapping_device/trackers/passed_tracker.rb
 - lib/tapping_device/version.rb
 - tapping_device.gemspec
 homepage: https://github.com/st0012/tapping_device