gitlab-labkit 0.39.0 → 0.41.0

data/lib/labkit/rspec/README.md

@@ -0,0 +1,132 @@
+# Labkit RSpec Support
+
+This module provides RSpec matchers for testing Labkit functionality in your Rails applications.
+
+## Setup
+
+You must explicitly require the RSpec matchers in your test files:
+
+```ruby
+# In your spec_helper.rb or rails_helper.rb
+require 'labkit/rspec/matchers'
+```
+
+This approach ensures that:
+- Test dependencies are not loaded in production environments
+- You have explicit control over which matchers are available
+- The gem remains lightweight for non-testing use cases
+
+
+## Available Matchers
+
+### Covered Experience Matchers
+
+These matchers help you test that your code properly instruments covered experiences with the expected metrics.
+
+#### `start_covered_experience`
+
+Tests that a covered experience is started (checkpoint=start metric is incremented).
+
+```ruby
+expect { subject }.to start_covered_experience('rails_request')
+
+# Test that it does NOT start
+expect { subject }.not_to start_covered_experience('rails_request')
+```
+
+#### `checkpoint_covered_experience`
+
+Tests that a covered experience checkpoint is recorded (checkpoint=intermediate metric is incremented).
+
+```ruby
+expect { subject }.to checkpoint_covered_experience('rails_request')
+
+# Test that it does NOT checkpoint
+expect { subject }.not_to checkpoint_covered_experience('rails_request')
+```
+
+#### `resume_covered_experience`
+
+Tests that a covered experience is resumed (checkpoint=intermediate metric is incremented). This is an alias for `checkpoint_covered_experience` that provides more semantic meaning when testing code that resumes a covered experience previously started.
+
+```ruby
+expect { subject }.to resume_covered_experience('rails_request')
+
+# Test that it does NOT resume
+expect { subject }.not_to resume_covered_experience('rails_request')
+```
+
+#### `complete_covered_experience`
+
+Tests that a covered experience is completed with the expected metrics:
+- `gitlab_covered_experience_checkpoint_total` (with checkpoint=end)
+- `gitlab_covered_experience_total` (with error flag)
+- `gitlab_covered_experience_apdex_total` (with success flag)
+
+```ruby
+# Test successful completion
+expect { subject }.to complete_covered_experience('rails_request')
+
+# Test completion with error
+expect { subject }.to complete_covered_experience('rails_request', error: true, success: false)
+
+# Test that it does NOT complete
+expect { subject }.not_to complete_covered_experience('rails_request')
+```
+
+## Example Usage
+
+### In your spec_helper.rb or rails_helper.rb:
+
+```ruby
+# spec/spec_helper.rb or spec/rails_helper.rb
+require 'gitlab-labkit'
+
+# Explicitly require the RSpec matchers
+require 'labkit/rspec/matchers'
+
+RSpec.configure do |config|
+  # Your other RSpec configuration...
+end
+```
+
+### In your test files:
+
+```ruby
+RSpec.describe MyController, type: :controller do
+  describe '#index' do
+    it 'instruments the request properly' do
+      expect { get :index }.to start_covered_experience('rails_request')
+        .and complete_covered_experience('rails_request')
+    end
+
+    context 'when an error occurs' do
+      before do
+        allow(MyService).to receive(:call).and_raise(StandardError)
+      end
+
+      it 'records the error in metrics' do
+        expect { get :index }.to complete_covered_experience('rails_request', error: true, success: false)
+      end
+    end
+  end
+end
+```
+
+### For individual spec files (alternative approach):
+
+```ruby
+# spec/controllers/my_controller_spec.rb
+require 'spec_helper'
+require 'labkit/rspec/matchers' # Can also be required per-file if needed
+
+RSpec.describe MyController do
+  # Your tests using the matchers...
+end
+```
+
+## Requirements
+
+- The covered experience must be registered in `Labkit::CoveredExperience::Registry`
+- Metrics must be properly configured in your test environment
+- The code under test must use Labkit's covered experience instrumentation

data/lib/labkit/rspec/matchers/covered_experience_matchers.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+# RSpec matchers for testing Labkit CoveredExperience functionality
+#
+# This file must be explicitly required in your test setup:
+#   require 'labkit/rspec/matchers'
+
+raise LoadError, "RSpec is not loaded. Please require 'rspec' before requiring 'labkit/rspec/matchers'" unless defined?(RSpec)
+
+module Labkit
+  module RSpec
+    module Matchers
+      # Helper module for CoveredExperience functionality
+      module CoveredExperience
+        def attributes(covered_experience_id)
+          raise ArgumentError, "covered_experience_id is required" if covered_experience_id.nil?
+
+          definition = Labkit::CoveredExperience::Registry.new[covered_experience_id]
+          definition.to_h.slice(:covered_experience, :feature_category, :urgency)
+        end
+
+        def checkpoint_counter
+          Labkit::Metrics::Client.get(:gitlab_covered_experience_checkpoint_total)
+        end
+
+        def total_counter
+          Labkit::Metrics::Client.get(:gitlab_covered_experience_total)
+        end
+
+        def apdex_counter
+          Labkit::Metrics::Client.get(:gitlab_covered_experience_apdex_total)
+        end
+      end
+    end
+  end
+end
+
+# Matcher for verifying CoveredExperience start metrics instrumentation.
+#
+# Usage:
+#   expect { subject }.to start_covered_experience('rails_request')
+#
+# This matcher verifies that the following metric is incremented:
+# - gitlab_covered_experience_checkpoint_total (with checkpoint=start)
+#
+# Parameters:
+# - covered_experience_id: Required. The ID of the covered experience (e.g., 'rails_request')
+RSpec::Matchers.define :start_covered_experience do |covered_experience_id|
+  include Labkit::RSpec::Matchers::CoveredExperience
+
+  description { "start covered experience '#{covered_experience_id}'" }
+  supports_block_expectations
+
+  match do |actual|
+    labels = attributes(covered_experience_id)
+
+    checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "start")).to_i
+
+    actual.call
+
+    checkpoint_after = checkpoint_counter&.get(labels.merge(checkpoint: "start")).to_i
+
+    @checkpoint_change = checkpoint_after - checkpoint_before
+
+    @checkpoint_change == 1
+  end
+
+  failure_message do
+    "Failed to checkpoint covered experience '#{covered_experience_id}':\n" \
+      "expected checkpoint='start' counter to increase by 1, but increased by #{@checkpoint_change}"
+  end
+end
+
+# Matcher for verifying CoveredExperience checkpoint metrics instrumentation.
+#
+# Usage:
+#   expect { subject }.to checkpoint_covered_experience('rails_request')
+#
+# This matcher verifies that the following metric is incremented:
+# - gitlab_covered_experience_checkpoint_total (with checkpoint=intermediate)
+#
+# Parameters:
+# - covered_experience_id: Required. The ID of the covered experience (e.g., 'rails_request')
+RSpec::Matchers.define :checkpoint_covered_experience do |covered_experience_id, by: 1|
+  include Labkit::RSpec::Matchers::CoveredExperience
+
+  description { "checkpoint covered experience '#{covered_experience_id}'" }
+  supports_block_expectations
+
+  match do |actual|
+    labels = attributes(covered_experience_id)
+
+    checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "intermediate")).to_i
+
+    actual.call
+
+    checkpoint_after = checkpoint_counter&.get(labels.merge(checkpoint: "intermediate")).to_i
+    @checkpoint_change = checkpoint_after - checkpoint_before
+
+    # Automatic checkpoints can be created in-between depending on the context,
+    # such as pushing experiences to background jobs. For this reason, we check
+    # that the value increases by at least "by".
+    @checkpoint_change >= by
+  end
+
+  failure_message do
+    "Failed to checkpoint covered experience '#{covered_experience_id}':\n" \
+      "expected checkpoint='intermediate' counter to increase by at least #{by}, but increased by #{@checkpoint_change}"
+  end
+
+  match_when_negated do |actual|
+    labels = attributes(covered_experience_id)
+
+    checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "intermediate")).to_i
+
+    actual.call
+
+    checkpoint_after = checkpoint_counter&.get(labels.merge(checkpoint: "intermediate")).to_i
+    @checkpoint_change = checkpoint_after - checkpoint_before
+
+    @checkpoint_change.zero?
+  end
+
+  failure_message_when_negated do
+    "Expected covered experience '#{covered_experience_id}' NOT to checkpoint:\n" \
+      "expected checkpoint='intermediate' counter not to increase, but increased by #{@checkpoint_change}"
+  end
+end
+
+# Alias for checkpoint_covered_experience matcher
+RSpec::Matchers.alias_matcher :resume_covered_experience, :checkpoint_covered_experience
+
+# Matcher for verifying CoveredExperience completion metrics instrumentation.
+#
+# Usage:
+#   expect { subject }.to complete_covered_experience('rails_request')
+#
+# This matcher verifies that the following metrics are incremented with specific labels:
+# - gitlab_covered_experience_checkpoint_total (with checkpoint=end)
+# - gitlab_covered_experience_total (with error=false)
+# - gitlab_covered_experience_apdex_total (with success=true)
+#
+# Parameters:
+# - covered_experience_id: Required. The ID of the covered experience (e.g., 'rails_request')
+# - error: Optional. The expected error flag for gitlab_covered_experience_total (false by default)
+# - success: Optional. The expected success flag for gitlab_covered_experience_apdex_total (true by default)
+RSpec::Matchers.define :complete_covered_experience do |covered_experience_id, error: false, success: true|
+  include Labkit::RSpec::Matchers::CoveredExperience
+
+  description { "complete covered experience '#{covered_experience_id}'" }
+  supports_block_expectations
+
+  match do |actual|
+    labels = attributes(covered_experience_id)
+
+    checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
+    total_before = total_counter&.get(labels.merge(error: error)).to_i
+    apdex_before = apdex_counter&.get(labels.merge(success: success)).to_i
+
+    actual.call
+
+    checkpoint_after = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
+    total_after = total_counter&.get(labels.merge(error: error)).to_i
+    apdex_after = apdex_counter&.get(labels.merge(success: success)).to_i
+    @checkpoint_change = checkpoint_after - checkpoint_before
+    @total_change = total_after - total_before
+    @apdex_change = apdex_after - apdex_before
+
+    @checkpoint_change == 1 && @total_change == 1 && @apdex_change == (error ? 0 : 1)
+  end
+
+  failure_message do
+    "Failed to complete covered experience '#{covered_experience_id}':\n" \
+      "expected checkpoint='end' counter to increase by 1, but increased by #{@checkpoint_change}\n" \
+      "expected total='error: #{error}' counter to increase by 1, but increased by #{@total_change}\n" \
+      "expected apdex='success: #{success}' counter to increase by 1, but increased by #{@apdex_change}"
+  end
+
+  match_when_negated do |actual|
+    labels = attributes(covered_experience_id)
+
+    checkpoint_before = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
+    total_before = total_counter&.get(labels.merge(error: error)).to_i
+    apdex_before = apdex_counter&.get(labels.merge(success: success)).to_i
+
+    actual.call
+
+    checkpoint_after = checkpoint_counter&.get(labels.merge(checkpoint: "end")).to_i
+    total_after = total_counter&.get(labels.merge(error: error)).to_i
+    apdex_after = apdex_counter&.get(labels.merge(success: success)).to_i
+    @checkpoint_change = checkpoint_after - checkpoint_before
+    @total_change = total_after - total_before
+    @apdex_change = apdex_after - apdex_before
+
+    @checkpoint_change.zero? && @total_change.zero? && @apdex_change == (error ? 1 : 0)
+  end
+
+  failure_message_when_negated do
+    "Failed covered experience '#{covered_experience_id}' NOT to complete:\n" \
+      "expected checkpoint='end' counter to increase by 0, but increased by #{@checkpoint_change}\n" \
+      "expected total='error: #{error}' counter to increase by 0, but increased by #{@total_change}\n" \
+      "expected apdex='success: #{success}' counter to increase by 0, but increased by #{@apdex_change}"
+  end
+end

data/lib/labkit/rspec/matchers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# RSpec matchers loader for Labkit
+#
+# This file loads all available RSpec matchers for Labkit.
+# It must be explicitly required in your test setup.
+
+raise LoadError, "RSpec is not loaded. Please require 'rspec' before requiring 'labkit/rspec/matchers'" unless defined?(RSpec)
+
+require_relative 'matchers/covered_experience_matchers'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 0.39.0
+  version: 0.41.0
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -91,6 +91,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
 - !ruby/object:Gem::Dependency
   name: opentracing
   requirement: !ruby/object:Gem::Requirement
@@ -433,6 +447,8 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- config/covered_experiences/schema.json
+- config/covered_experiences/testing_sample.yml
 - gitlab-labkit.gemspec
 - lib/gitlab-labkit.rb
 - lib/labkit/context.rb
@@ -442,6 +458,13 @@ files:
 - lib/labkit/correlation/grpc/client_interceptor.rb
 - lib/labkit/correlation/grpc/grpc_common.rb
 - lib/labkit/correlation/grpc/server_interceptor.rb
+- lib/labkit/covered_experience.rb
+- lib/labkit/covered_experience/README.md
+- lib/labkit/covered_experience/current.rb
+- lib/labkit/covered_experience/error.rb
+- lib/labkit/covered_experience/experience.rb
+- lib/labkit/covered_experience/null.rb
+- lib/labkit/covered_experience/registry.rb
 - lib/labkit/excon_publisher.rb
 - lib/labkit/fips.rb
 - lib/labkit/httpclient_publisher.rb
@@ -463,12 +486,18 @@ files:
 - lib/labkit/middleware/sidekiq/context.rb
 - lib/labkit/middleware/sidekiq/context/client.rb
 - lib/labkit/middleware/sidekiq/context/server.rb
+- lib/labkit/middleware/sidekiq/covered_experience.rb
+- lib/labkit/middleware/sidekiq/covered_experience/client.rb
+- lib/labkit/middleware/sidekiq/covered_experience/server.rb
 - lib/labkit/middleware/sidekiq/server.rb
 - lib/labkit/middleware/sidekiq/tracing.rb
 - lib/labkit/middleware/sidekiq/tracing/client.rb
 - lib/labkit/middleware/sidekiq/tracing/server.rb
 - lib/labkit/middleware/sidekiq/tracing/sidekiq_common.rb
 - lib/labkit/net_http_publisher.rb
+- lib/labkit/rspec/README.md
+- lib/labkit/rspec/matchers.rb
+- lib/labkit/rspec/matchers/covered_experience_matchers.rb
 - lib/labkit/system.rb
 - lib/labkit/tracing.rb
 - lib/labkit/tracing/abstract_instrumenter.rb
@@ -525,7 +554,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Instrumentation for GitLab
 test_files: []