tracing-matchers 1.0.0

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "tracing/matchers"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/tracing/matchers.rb

@@ -0,0 +1,155 @@
+require "tracing/matchers/version"
+require "tracing/matchers/span_matchers"
+require "tracing/matchers/have_traces"
+require "tracing/matchers/have_spans"
+require "tracing/matchers/have_span"
+
+module Tracing
+  module Matchers
+    # The `have_traces` matcher tests that the tracer traced any or a specific
+    # number of **traces**.
+    #
+    # @example
+    #
+    #   # Passes if tracer traced any trace
+    #   expect(tracer).to have_spans
+    #
+    #   # Passes if tracer traced exactly 10 distinct traces
+    #   expect(tracer).to have_spans(10)
+    #
+    #   # Passes if tracer started any trace
+    #   expect(tracer).to have_spans.started
+    #
+    #   # Passes if tracer has any finished traces
+    #   expect(tracer).to have_spans.finished
+    #
+    # @note It's possible to chain `started` and `finished` at the same time.
+    #  Expect that only the last method will be applied e.g. `have_spans.finished.started`
+    #  will result in application of `started`.
+    #
+    # @param [Fixnum] n expected number of distinct traces
+    # @return [HaveTraces]
+    #
+    # @see HaveTraces#started
+    # @see HaveTraces#finished
+    def have_traces(n = anything)
+      Tracing::Matchers::HaveTraces.new(n)
+    end
+
+    # The `have_spans` matcher tests that the tracer traced any or a specific
+    # number of **spans**.
+    #
+    # @example
+    #
+    #   # Passes if either `tracer.spans`, or `tracer.finished_spans` includes any span
+    #   expect(tracer).to have_spans
+    #
+    #   # Passes if either `tracer.spans`, or `tracer.finished_spans` includes exactly 10 spans
+    #   expect(tracer).to have_spans(10)
+    #
+    #   # Passes if `tracer.spans` includes any span
+    #   expect(tracer).to have_spans.started
+    #
+    #   # Passes if `tracer.finished_spans` includes any span
+    #   expect(tracer).to have_spans.finished
+    #
+    # @note It's possible to chain `started` and `finished` at the same time.
+    #  Expect that only the last method will be applied e.g. `have_spans.finished.started`
+    #  will result in application of `started`.
+    #
+    # @param [Fixnum] n expected number of traced spans
+    # @return [HaveSpans]
+    #
+    # @see HaveSpans#started
+    # @see HaveSpans#finished
+    def have_spans(n = anything)
+      Tracing::Matchers::HaveSpans.new(n)
+    end
+
+    # The `have_span` matcher tests that the tracer traced a span matching a criteria.
+    #
+    # @example
+    #
+    #   # Behaves very similar to have_traces without any arguments.
+    #   expect(tracer).to have_span
+    #
+    #   # Passes if the tracer traced span with the operation name "User Load".
+    #   expect(tracer).to have_span("User Load")
+    #
+    #   # Passes if the tracer traced span with the operation name "User Load"
+    #   # which is still in progress.
+    #   expect(tracer).to have_span("User Load").in_progress
+    #
+    #   # Same as above
+    #   expect(tracer).to have_span("User Load").started
+    #
+    #   # Passes if the tracer traced span with the operation name "User Load"
+    #   # which has finished.
+    #   expect(tracer).to have_span("User Load").finished
+    #
+    #   # Passes if the tracer traced any span which has any tag
+    #   expect(tracer).to have_span.with_tags
+    #
+    #   # Passes if the tracer traced span with the operation name "User Load"
+    #   # and which has any tag
+    #   expect(tracer).to have_span("User Load").with_tags
+    #
+    #   # Passes if the tracer traced span with the operation name "User Load"
+    #   # and which has a tag 'component' => 'ActiveRecord'.
+    #   expect(tracer).to have_span("User Load").with_tags('component' => 'ActiveRecord')
+    #
+    #   # Passes if the tracer traced any span which has any log entry
+    #   expect(tracer).to have_span.with_logs
+    #
+    #   # Passes if the tracer traced span with the operation name "User Load"
+    #   # and which has a log entry with event 'error'.
+    #   expect(tracer).to have_span("User Load").with_logs(event: 'error')
+    #
+    #   # Passes if the tracer traced any span which has any entry in a baggage
+    #   expect(tracer).to have_span.with_baggae
+    #
+    #   # Passes if the tracer traced span with the operation name "User Load"
+    #   # and which has a baggage with 'account_id' => '1'
+    #   expect(tracer).to have_span("User Load").with_baggae('account_id' => '1')
+    #
+    #   # Passes if the tracer traced any span which has a parent
+    #   expect(tracer).to have_span.with_parent
+    #
+    #   # Passes if the tracer traced any span which has root_span as a parent
+    #   expect(tracer).to have_span.child_of(root_span)
+    #
+    #   # Passes if the tracer traced span with the operation name "User Load"
+    #   # and which has a parent span with operation name "Authentication".
+    #   expect(tracer).to have_span("User Load").child_of("Authentication")
+    #
+    #   # Passes if the tracer traced span with the operation name "User Load"
+    #   # which has a tag 'component' => 'ActiveRecord',
+    #   # has any log entry,
+    #   # has a baggage with 'account_id' => '1',
+    #   # and is child of a span with operation name "Authentication".
+    #   expect(tracer).to have_span("User Load")
+    #                     .with_tags('component' => 'ActiveRecord')
+    #                     .with_logs
+    #                     .with_baggage('account_id' => '1')
+    #                     .child_of("Authentication")
+    #
+    # @param [String] operation_name operation name of a searched span
+    # @return [HaveSpan]
+    #
+    # @see HaveSpan#in_progress
+    # @see HaveSpan#started
+    # @see HaveSpan#finished
+    # @see HaveSpan#with_tags
+    # @see HaveSpan#with_logs
+    # @see HaveSpan#with_baggage
+    # @see HaveSpan#with_parent
+    # @see HaveSpan#child_of
+    def have_span(operation_name = anything)
+      Tracing::Matchers::HaveSpan.new(operation_name)
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include Tracing::Matchers
+end

data/lib/tracing/matchers/have_span.rb

@@ -0,0 +1,101 @@
+module Tracing
+  module Matchers
+    # @private
+    class HaveSpan
+      def initialize(operation_name)
+        @expected = operation_name
+        @predicates = []
+      end
+
+      def in_progress
+        @state_predicate = RSpec::Matchers::BuiltIn::BePredicate.new(:be_started)
+        self
+      end
+      alias :started :in_progress
+
+      def finished
+        @state_predicate = RSpec::Matchers::BuiltIn::BePredicate.new(:be_finished)
+        self
+      end
+
+      def with_tag(*args)
+        @predicates << Tracing::Matchers::Span::HaveTag.new(*args)
+        self
+      end
+      alias :with_tags :with_tag
+
+      def with_log(**fields)
+        @predicates << Tracing::Matchers::Span::HaveLog.new(**fields)
+        self
+      end
+      alias :with_logs :with_log
+
+      def with_baggage(*args)
+        @predicates << Tracing::Matchers::Span::HaveBaggage.new(*args)
+        self
+      end
+
+      def child_of(parent = :any)
+        @predicates << Tracing::Matchers::Span::BeChildOf.new(parent)
+        self
+      end
+      alias :with_parent :child_of
+
+      # @return [Boolean]
+      def matches?(tracer)
+        @subject = tracer
+        @actual = actual_spans
+
+        @actual.any? { |span| all_predicates.all? { |matcher| matcher.matches?(span) } }
+      end
+
+      # @return [String]
+      def description
+        "have a#{expected_span_description}"
+      end
+
+      # @return [String]
+      def failure_message
+        "expected a#{expected_span_description}"
+      end
+      alias :failure_message_for_should :failure_message
+
+      # @return [String]
+      def failure_message_when_negated
+        "did not expect#{expected_span_description}"
+      end
+      alias :failure_message_for_should_not :failure_message_when_negated
+
+      private
+
+      def expected_span_description
+        desc = ""
+        desc << " #{@state_predicate.description.gsub('be ', '')}" if state_predicate?
+        desc << " span"
+        desc << " with operation name \"#{@expected}\"" if operation_name?
+        @predicates.each { |matcher| desc << " #{matcher.description.gsub('have', 'with')}" }
+        desc
+      end
+
+      def actual_spans
+        @subject.spans.select(&expected_predicate)
+      end
+
+      def expected_predicate
+        operation_name? ? -> (span) { span.operation_name == @expected } : -> (_) { true }
+      end
+
+      def operation_name?
+        @expected.is_a?(String)
+      end
+
+      def state_predicate?
+        @state_predicate
+      end
+
+      def all_predicates
+        @all_predicates = (@predicates + [@state_predicate]).compact
+      end
+    end
+  end
+end

data/lib/tracing/matchers/have_spans.rb

@@ -0,0 +1,80 @@
+module Tracing
+  module Matchers
+    # @private
+    class HaveSpans
+      def initialize(n)
+        @expected = n
+      end
+
+      def started
+        @state = :started
+        self
+      end
+
+      def finished
+        @state = :finished
+        self
+      end
+
+      # @return [Boolean]
+      def matches?(tracer)
+        @subject = tracer
+
+        if exactly?
+          @actual = spans.size
+          @actual == @expected
+        else
+          spans.any?
+        end
+      end
+
+      # @return [String]
+      def description
+        desc = "have "
+        desc << "exactly #{@expected} " if exactly?
+        desc << "spans #{@state}"
+        desc.strip
+      end
+
+      # @return [String]
+      def failure_message
+        if exactly?
+          message = "expected #{@expected} spans"
+          message << " #{@state}" if @state
+          message << ", got #{@actual}"
+          message
+        else
+          "expected any span #{@state}".strip
+        end
+      end
+      alias :failure_message_for_should :failure_message
+
+      # @return [String]
+      def failure_message_when_negated
+        if exactly?
+          message = "did not expect #{@expected} spans"
+          message << " #{@state}" if @state
+          message << ", got #{@actual}"
+          message
+        else
+          "did not expect spans #{@state}".strip
+        end
+      end
+      alias :failure_message_for_should_not :failure_message_when_negated
+
+      private
+
+      def state
+        @state || :started
+      end
+
+      def spans
+        state == :finished ? @subject.finished_spans : @subject.spans
+      end
+
+      def exactly?
+        @expected.is_a?(Fixnum)
+      end
+    end
+  end
+end

data/lib/tracing/matchers/have_traces.rb

@@ -0,0 +1,89 @@
+module Tracing
+  module Matchers
+    # @private
+    class HaveTraces
+      def initialize(n)
+        @expected = n
+      end
+
+      def started
+        @state = :started
+        self
+      end
+
+      def finished
+        @state = :finished
+        self
+      end
+
+      # @return [Boolean]
+      def matches?(tracer)
+        @subject = tracer
+
+        if exactly?
+          @actual = traces.size
+          @actual == @expected
+        else
+          traces.any?
+        end
+      end
+
+      # @return [String]
+      def description
+        desc = "have "
+        desc << "exactly #{@expected} " if exactly?
+        desc << "traces #{@state}"
+        desc.strip
+      end
+
+      # @return [String]
+      def failure_message
+        if exactly?
+          message = "expected #{@expected} traces"
+          message << " #{@state}" if @state
+          message << ", got #{@actual}"
+          message
+        else
+          "expected any trace #{@state}".strip
+        end
+      end
+      alias :failure_message_for_should :failure_message
+
+      # @return [String]
+      def failure_message_when_negated
+        if exactly?
+          message = "did not expect #{@expected} traces"
+          message << " #{@state}" if @state
+          message << ", got #{@actual}"
+          message
+        else
+          "did not expect traces #{@state}".strip
+        end
+      end
+      alias :failure_message_for_should_not :failure_message_when_negated
+
+      private
+
+      def state
+        @state || :started
+      end
+
+      def exactly?
+        @expected.is_a?(Fixnum)
+      end
+
+      def traces
+        @subject.spans
+          .group_by { |span| span.context.trace_id }
+          .map { |trace_id, spans| Trace.new(trace_id, spans) }
+          .select { |trace| @state == :finished ? trace.finished? : true }
+      end
+
+      class Trace < Struct.new(:trace_id, :spans)
+        def finished?
+          spans.all? { |span| !span.in_progress? }
+        end
+      end
+    end
+  end
+end