TraceSpy

TraceSpy is a wrapper around TracePoint to expose more power in matching against various cases of Ruby and getting value from composable traces.

I would suggest reading into Qo to get an idea of how the matchers work.

Alpha Version - What that means

When I say alpha I mean the API is going to be in flux as I experiment with things. This is a proof-of-concept to demonstrate that the idea works. As I learn more about TracePoint and potential uses you may see things shifting.

These will always be done with "minor" version bumps, i.e. 0.0.3 -> 0.1.0 for breaking APIs. For now, locking to static versions would be best if you intend to leverage it for more than just testing.

1.0.0 will be considered a stable API, and will come after the gem has had some time to settle.

Usage

The methods themselves are documented, and I'll work on expanding this section later with more examples and ideas as I can.

def testing(a, b, c)
  raise 'heck' if a.is_a?(Numeric) && a > 20

  d = 5 if c.is_a?(Numeric) && c > 3

  a + b + c
end

testing_spy = TraceSpy::Method.new(:testing) do |spy|
  # On the arguments, given as keywords, will yield arguments to the block
  spy.on_arguments do |m|
    m.when(a: String, b: String, c: String) do |v|
      puts "Oh hey! You called me with strings: #{v}"
    end

    m.when(a: 1, b: 2, c: 3) do |v|
      puts "My args were 1, 2, 3: #{v}"
    end
  end

  # On an exception, will yield exception to the block
  spy.on_exception do |m|
    m.when(RuntimeError) do |e|
      puts "I encountered an error: #{e}"
    end
  end

  # On a return value, will yield the return to the block
  spy.on_return do |m|
    m.when(String) do |v|
      puts "Strings in, Strings out no?: #{v}. I got this in though: #{spy.current_arguments}"
    end

    m.when(:even?) do |v|
      puts "I got an even return: #{v}"
    end
  end

  # On a local variable being present:
  spy.on_locals do |m|
    m.when(d: 5) do |v|
      puts "I saw d was a local in here!: #{v}. I could also ask this: #{spy.current_local_variables}"
    end
  end
end

# If you want to manually enable/disable the trace, use:
#
#   testing_spy.enable
#   testing_spy.disable
#
# Otherwise, use:

# Outside of this block, the trace is inactive:
testing_spy.with_tracing do
  p testing(1, 2, 3)
  # My args were 1, 2, 3: {:a=>1, :b=>2, :c=>3}
  # I got an even return: 6
  # => 6

  p testing(21, 2, 3) rescue 'nope'
  # I encountered an error: heck
  # => 'nope'

  p testing(*%w(foo bar baz))
  # Oh hey! You called me with strings: {:a=>"foo", :b=>"bar", :c=>"baz"}
  # Strings in, Strings out no?: foobarbaz
  # => 'foobarbaz'

  p testing(1, 2, 4)
  # I saw d was a local in here!: {:a=>1, :b=>2, :c=>4, :d=>5}
  # => 7
end

# Back to normal
testing(1, 2, 3)
# => 6

Installation

Add this line to your application's Gemfile:

gem 'trace_spy'

And then execute:

$ bundle

Or install it yourself as:

$ gem install trace_spy

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/baweaver/trace_spy. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the TraceSpy project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.