yabeda 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5aed70338bdfe24c4505a3cbe51cb4853c7c0e0c1842ef1cee93480ef517c02
-  data.tar.gz: 95dc76b40980f227abe24c7bf70339d47d81eaa91e6bdfa354c8b6e6b93c8170
+  metadata.gz: 262fe8c41ef493e3792e67b3e569f3820f8fc8de11a5795807d8d81efe8e0d9f
+  data.tar.gz: d86b4a968f1894ce65af4976873135957a122672cd58453023d38792b60c4db7
 SHA512:
-  metadata.gz: 77e865d851f2e9f2a168426983df6693c9e655e0349107aafd25594eea12f9f83c14da519abbdfc5826f8c0e208d68b2a0616735771ba5ec82bde7acb3e71085
-  data.tar.gz: aa7596a3de80b063845d552136c882cbdf46e772a1f53998058ba894dc8428290fdbae391ef241f2264dd5e76bd41be8cfab0b8afad654152b50d3b47fd0ab3b
+  metadata.gz: 22c41d84fb0efbb8ca1802e02c1c4e6636fc8a2ae05c22775d4390ddc5ddfd0926b97464d6b2702e6b82a1b8709d66bf391bcb7aa6ed05df9a640a0143817889
+  data.tar.gz: ad5e58fc8b678c0764b6d8f3677c56a08d087dcbc9407b3a6864fa0e85226a773dce2efaa365d8bed0d0c25db300829811688819a407dee86bcefbea439e2232

data/.rubocop.yml

@@ -23,6 +23,12 @@ RSpec/LetSetup:
 RSpec/MultipleExpectations:
   Enabled: false
 
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 4
+
 Bundler/OrderedGems:
   Enabled: false
 
@@ -52,3 +58,6 @@ Style/HashTransformKeys:
 
 Style/HashTransformValues:
   Enabled: true
+
+Style/Documentation:
+  Enabled: false

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## Unreleased
 
+## 0.11.0 - 2021-09-25
+
+### Added
+
+- RSpec matchers `increment_yabeda_counter`, `update_yabeda_gauge`, and `measure_yabeda_histogram` for convenient testing. [#25](https://github.com/yabeda-rb/yabeda/pull/25) by [@Envek][]
+- Automatic setup of RSpec on `require "yabeda/rspec"`
+- Special test adapter that collects metric changes in memory
+
 ## 0.10.1 - 2021-08-30
 
 ### Fixed

data/README.md

@@ -162,6 +162,44 @@ Config key | Type     | Default | Description |
 
 These are only enabled in debug mode. To enable it either set `debug` config key to `true` (e.g. by specifying `YABEDA_DEBUG=true` in your environment variables or executing `Yabeda.debug!` in your code).
 
+## Testing
+
+### RSpec
+
+Add the following to your `rails_helper.rb` (or `spec_helper.rb`):
+
+```ruby
+require "yabeda/rspec"
+```
+
+Now you can use `increment_yabeda_counter`, `update_yabeda_gauge`, and `measure_yabeda_histogram` matchers:
+
+```ruby
+it "increments counters" do
+  expect { subject }.to increment_yabeda_counter(Yabeda.myapp.foo_count).by(3)
+end
+```
+
+You can scope metrics by used tags with `with_tags`:
+
+```ruby
+it "updates gauges" do
+  expect { subject }.to \
+    update_yabeda_gauge("some_gauge_name").
+    with_tags(method: "command", command: "subscribe")
+end
+```
+
+Note that tags you specified doesn't need to be exact, but can be a subset of tags used on metric update. In this example updates with following sets of tags `{ method: "command", command: "subscribe", status: "SUCCESS" }` and `{ method: "command", command: "subscribe", status: "FAILURE" }` will make test example to pass.
+
+And check for values with `by` for counters, `to` for gauges, and `with` for gauges and histograms (and you [can use other matchers here](https://relishapp.com/rspec/rspec-expectations/v/3-10/docs/composing-matchers)):
+
+```ruby
+expect { subject }.to \
+  measure_yabeda_histogram(Yabeda.something.anything_runtime).
+  with(be_between(0.005, 0.05))
+```
+
 ## Roadmap (aka TODO or Help wanted)
 
  - Ability to change metric settings for individual adapters

data/lib/yabeda/dsl/class_methods.rb

@@ -11,7 +11,6 @@ require "yabeda/dsl/metric_builder"
 module Yabeda
   # DSL for ease of work with Yabeda
   module DSL
-    # rubocop: disable Style/Documentation
     module ClassMethods
       # Block for grouping and simplifying configuration of related metrics
       def configure(&block)
@@ -110,6 +109,5 @@ module Yabeda
         group.register_metric(metric)
       end
     end
-    # rubocop: enable Style/Documentation
   end
 end

data/lib/yabeda/metric.rb

@@ -29,5 +29,9 @@ module Yabeda
     def tags
       (Yabeda.groups[group].default_tags.keys + Array(super)).uniq
     end
+
+    def inspect
+      "#<#{self.class.name}: #{[@group, @name].compact.join('.')}>"
+    end
   end
 end

data/lib/yabeda/rspec/base_matcher.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Yabeda
+  module RSpec
+    # Notes:
+    #  +expected+ is always a metric instance
+    #  +actual+ is always a block of code
+    # Example:
+    #  expect { anything }.to do_whatever_with_yabeda_metric(Yabeda.something)
+    class BaseMatcher < ::RSpec::Matchers::BuiltIn::BaseMatcher
+      attr_reader :tags, :metric
+
+      # Specify a scope of labels (tags). Subset of tags can be specified.
+      def with_tags(tags)
+        @tags = tags
+        self
+      end
+
+      def initialize(expected)
+        @expected = @metric = resolve_metric(expected)
+      rescue KeyError
+        raise ArgumentError, <<~MSG
+          Pass metric name or metric instance to matcher (e.g. `increment_yabeda_counter(Yabeda.metric_name)` or \
+          increment_yabeda_counter('metric_name')). Got #{expected.inspect} instead
+        MSG
+      end
+
+      # RSpec doesn't define this method, but it is more convenient to rely on +match_when_negated+ method presence
+      def does_not_match?(actual)
+        @actual = actual
+        if respond_to?(:match_when_negated)
+          match_when_negated(expected, actual)
+        else
+          !match(expected, actual)
+        end
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      # Pretty print metric name (expected is expected to always be a Yabeda metric instance)
+      def expected_formatted
+        "Yabeda.#{[metric.group, metric.name].compact.join('.')}"
+      end
+
+      private
+
+      def resolve_metric(instance_or_name)
+        return instance_or_name if instance_or_name.is_a? Yabeda::Metric
+
+        Yabeda.metrics.fetch(instance_or_name.to_s)
+      end
+
+      # Filter metric changes by tags.
+      # If tags specified, treat them as subset of real tags (to avoid bothering with default tags in tests)
+      def filter_matching_changes(changes)
+        return changes if tags.nil?
+
+        changes.select { |t, _v| t >= tags }
+      end
+    end
+  end
+end

data/lib/yabeda/rspec/increment_yabeda_counter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "./base_matcher"
+
+module Yabeda
+  module RSpec
+    # Checks whether Yabeda counter was incremented during test run or not
+    # @param metric [Yabeda::Counter,String,Symbol] metric instance or name
+    # @return [Yabeda::RSpec::IncrementYabedaCounter]
+    def increment_yabeda_counter(metric)
+      IncrementYabedaCounter.new(metric)
+    end
+
+    # Custom matcher class with implementation for +increment_yabeda_counter+
+    class IncrementYabedaCounter < BaseMatcher
+      def by(increment)
+        @expected_increment = increment
+        self
+      end
+
+      attr_reader :expected_increment
+
+      def initialize(*)
+        super
+        return if metric.is_a? Yabeda::Counter
+
+        raise ArgumentError, "Pass counter instance/name to `increment_yabeda_counter`. Got #{metric.inspect} instead"
+      end
+
+      def match(metric, block)
+        block.call
+
+        increments = filter_matching_changes(Yabeda::TestAdapter.instance.counters.fetch(metric))
+
+        increments.values.any? do |actual_increment|
+          expected_increment.nil? || values_match?(expected_increment, actual_increment)
+        end
+      end
+
+      def match_when_negated(metric, block)
+        unless expected_increment.nil?
+          raise NotImplementedError, <<~MSG
+            `expect(Yabeda.metric_name).not_to increment_yabeda_counter` doesn't support specifying increment
+             with `.by` as it can lead to false positives.
+          MSG
+        end
+
+        block.call
+
+        increments = filter_matching_changes(Yabeda::TestAdapter.instance.counters.fetch(metric))
+
+        increments.none?
+      end
+
+      def failure_message
+        "expected #{expected_formatted} " \
+        "to be incremented #{"by #{description_of(expected_increment)} " unless expected_increment.nil?}" \
+        "#{("with tags #{::RSpec::Support::ObjectFormatter.format(tags)} " if tags)}" \
+        "but #{actual_increments_message}"
+      end
+
+      def failure_message_when_negated
+        "expected #{expected_formatted} " \
+        "not to be incremented " \
+        "#{("with tags #{::RSpec::Support::ObjectFormatter.format(tags)} " if tags)}" \
+        "but #{actual_increments_message}"
+      end
+
+      def actual_increments_message
+        counter_increments = Yabeda::TestAdapter.instance.counters.fetch(metric)
+        if counter_increments.empty?
+          "no increments of this counter have been made"
+        elsif tags && counter_increments.key?(tags)
+          "has been incremented by #{counter_increments.fetch(tags)}"
+        else
+          "following increments have been made: #{::RSpec::Support::ObjectFormatter.format(counter_increments)}"
+        end
+      end
+    end
+  end
+end

data/lib/yabeda/rspec/measure_yabeda_histogram.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "./base_matcher"
+
+module Yabeda
+  module RSpec
+    # Checks whether Yabeda histogram was measured during test run or not
+    # @param metric [Yabeda::Histogram,String,Symbol] metric instance or name
+    # @return [Yabeda::RSpec::MeasureYabedaHistogram]
+    def measure_yabeda_histogram(metric)
+      MeasureYabedaHistogram.new(metric)
+    end
+
+    # Custom matcher class with implementation for +measure_yabeda_histogram+
+    class MeasureYabedaHistogram < BaseMatcher
+      def with(value)
+        @expected_value = value
+        self
+      end
+
+      attr_reader :expected_value
+
+      def initialize(*)
+        super
+        return if metric.is_a? Yabeda::Histogram
+
+        raise ArgumentError, "Pass histogram instance/name to `measure_yabeda_histogram`. Got #{metric.inspect} instead"
+      end
+
+      def match(metric, block)
+        block.call
+
+        measures = filter_matching_changes(Yabeda::TestAdapter.instance.histograms.fetch(metric))
+
+        measures.values.any? { |measure| expected_value.nil? || values_match?(expected_value, measure) }
+      end
+
+      def match_when_negated(metric, block)
+        unless expected_value.nil?
+          raise NotImplementedError, <<~MSG
+            `expect {}.not_to measure_yabeda_histogram` doesn't support specifying values with `.with`
+            as it can lead to false positives.
+          MSG
+        end
+
+        block.call
+
+        measures = filter_matching_changes(Yabeda::TestAdapter.instance.histograms.fetch(metric))
+
+        measures.none?
+      end
+
+      def failure_message
+        "expected #{expected_formatted} " \
+        "to be changed #{"to #{expected} " unless expected_value.nil?}" \
+        "#{("with tags #{::RSpec::Support::ObjectFormatter.format(tags)} " if tags)}" \
+        "but #{actual_changes_message}"
+      end
+
+      def failure_message_when_negated
+        "expected #{expected_formatted} " \
+        "not to be incremented " \
+        "#{("with tags #{::RSpec::Support::ObjectFormatter.format(tags)} " if tags)}" \
+        "but #{actual_changes_message}"
+      end
+
+      def actual_changes_message
+        measures = Yabeda::TestAdapter.instance.histograms.fetch(metric)
+        if measures.empty?
+          "no changes of this gauge have been made"
+        elsif tags && measures.key?(tags)
+          "has been changed to #{measures.fetch(tags)} with tags #{::RSpec::Support::ObjectFormatter.format(tags)}"
+        else
+          "following changes have been made: #{::RSpec::Support::ObjectFormatter.format(measures)}"
+        end
+      end
+    end
+  end
+end

data/lib/yabeda/rspec/update_yabeda_gauge.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "./base_matcher"
+
+module Yabeda
+  module RSpec
+    # Checks whether Yabeda gauge was set to some value during test run or not
+    # @param metric [Yabeda::Gauge,String,Symbol] metric instance or name
+    # @return [Yabeda::RSpec::UpdateYabedaGauge]
+    def update_yabeda_gauge(metric)
+      UpdateYabedaGauge.new(metric)
+    end
+
+    # Custom matcher class with implementation for +update_yabeda_gauge+
+    class UpdateYabedaGauge < BaseMatcher
+      def with(value)
+        @expected_value = value
+        self
+      end
+
+      attr_reader :expected_value
+
+      def initialize(*)
+        super
+        return if metric.is_a? Yabeda::Gauge
+
+        raise ArgumentError, "Pass gauge instance/name to `update_yabeda_gauge`. Got #{metric.inspect} instead"
+      end
+
+      def match(metric, block)
+        block.call
+
+        updates = filter_matching_changes(Yabeda::TestAdapter.instance.gauges.fetch(metric))
+
+        updates.values.any? { |update| expected_value.nil? || values_match?(expected_value, update) }
+      end
+
+      def match_when_negated(metric, block)
+        unless expected_value.nil?
+          raise NotImplementedError, <<~MSG
+            `expect(Yabeda.metric_name).not_to update_yabeda_gauge` doesn't support specifying values with `.with`
+            as it can lead to false positives.
+          MSG
+        end
+
+        block.call
+
+        updates = filter_matching_changes(Yabeda::TestAdapter.instance.gauges.fetch(metric))
+
+        updates.none?
+      end
+
+      def failure_message
+        "expected #{expected_formatted} " \
+        "to be changed #{"to #{expected_value} " unless expected_value.nil?}" \
+        "#{("with tags #{::RSpec::Support::ObjectFormatter.format(tags)} " if tags)}" \
+        "but #{actual_changes_message}"
+      end
+
+      def failure_message_when_negated
+        "expected #{expected_formatted} " \
+        "not to be changed " \
+        "#{("with tags #{::RSpec::Support::ObjectFormatter.format(tags)} " if tags)}" \
+        "but #{actual_changes_message}"
+      end
+
+      def actual_changes_message
+        updates = Yabeda::TestAdapter.instance.gauges.fetch(metric)
+        if updates.empty?
+          "no changes of this gauge have been made"
+        elsif tags && updates.key?(tags)
+          "has been changed to #{updates.fetch(tags)} with tags #{::RSpec::Support::ObjectFormatter.format(tags)}"
+        else
+          "following changes have been made: #{::RSpec::Support::ObjectFormatter.format(updates)}"
+        end
+      end
+    end
+  end
+end

data/lib/yabeda/rspec.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "./testing"
+
+module Yabeda
+  # RSpec integration for Yabeda: custom matchers, etc
+  module RSpec
+  end
+end
+
+require_relative "./rspec/increment_yabeda_counter"
+require_relative "./rspec/update_yabeda_gauge"
+require_relative "./rspec/measure_yabeda_histogram"
+
+::RSpec.configure do |config|
+  config.before(:suite) do
+    Yabeda.configure! unless Yabeda.already_configured?
+  end
+
+  config.after(:each) do
+    Yabeda::TestAdapter.instance.reset!
+  end
+
+  config.include(Yabeda::RSpec)
+end

data/lib/yabeda/test_adapter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+require_relative "./base_adapter"
+
+module Yabeda
+  # Fake monitoring system adapter that collects latest metric values for later inspection
+  class TestAdapter < BaseAdapter
+    include Singleton
+
+    attr_reader :counters, :gauges, :histograms
+
+    def initialize
+      @counters   = Hash.new { |ch, ck| ch[ck] = Hash.new { |th, tk| th[tk] = 0 } }
+      @gauges     = Hash.new { |gh, gk| gh[gk] = Hash.new { |th, tk| th[tk] = nil } }
+      @histograms = Hash.new { |hh, hk| hh[hk] = Hash.new { |th, tk| th[tk] = nil } }
+    end
+
+    # Call this method after every test example to quickly get blank state for the next test example
+    def reset!
+      [@counters, @gauges, @histograms].each do |collection|
+        collection.each_value(&:clear) # Reset tag-values hash to be empty
+      end
+    end
+
+    def register_counter!(metric)
+      @counters[metric]
+    end
+
+    def register_gauge!(metric)
+      @gauges[metric]
+    end
+
+    def register_histogram!(metric)
+      @histograms[metric]
+    end
+
+    def perform_counter_increment!(counter, tags, increment)
+      @counters[counter][tags] += increment
+    end
+
+    def perform_gauge_set!(gauge, tags, value)
+      @gauges[gauge][tags] = value
+    end
+
+    def perform_histogram_measure!(histogram, tags, value)
+      @histograms[histogram][tags] = value
+    end
+  end
+end

data/lib/yabeda/testing.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Include this file to get things prepared for testing
+
+require_relative "./test_adapter"
+
+Yabeda.register_adapter(:test, Yabeda::TestAdapter.instance)

data/lib/yabeda/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Yabeda
-  VERSION = "0.10.1"
+  VERSION = "0.11.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yabeda
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Andrey Novikov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-08-30 00:00:00.000000000 Z
+date: 2021-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: anyway_config
@@ -166,7 +166,14 @@ files:
 - lib/yabeda/histogram.rb
 - lib/yabeda/metric.rb
 - lib/yabeda/railtie.rb
+- lib/yabeda/rspec.rb
+- lib/yabeda/rspec/base_matcher.rb
+- lib/yabeda/rspec/increment_yabeda_counter.rb
+- lib/yabeda/rspec/measure_yabeda_histogram.rb
+- lib/yabeda/rspec/update_yabeda_gauge.rb
 - lib/yabeda/tags.rb
+- lib/yabeda/test_adapter.rb
+- lib/yabeda/testing.rb
 - lib/yabeda/version.rb
 - yabeda-logo.png
 - yabeda.gemspec