gitlab-experiment 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 453f39a65f699c77881655a8dbfd40d15133baa47e063b76278e2953c4b1de7c
-  data.tar.gz: 3cd7e33850a1d0725bd7f4c82bbcd9d8769c01c1e6663226dcc07acdf68d24ec
+  metadata.gz: 0e0e710a80403ae390bb66fd552656996ca271891cbc4b2cd758f064538442e5
+  data.tar.gz: 564ea70f574ebabef344f4f428cfad52a6213a35522834956db8eb8073a498e9
 SHA512:
-  metadata.gz: 9ba7cc88703891e0ff10a885b55e0f59911459ffa6de2a7102dececf803cf27ea0d0e62912409b543a537c6df1266e403c18d4aa96d6767cfa1f7ae64d638dd3
-  data.tar.gz: 5f292e0a952811292354e1d9e84705b88eb225b79819bdb00b3fcf55f7a06754ff87a8502ecd8b5016278629a2c6d83609566dad373bdb2f11d44eca4ed7cdd3
+  metadata.gz: b76011392395d1d0b0e1d7beeec6dc085ea6d7444c231b9dbbdac7f909248cce4ca16f551bb11215b2611ad504a63a593669b31e544d69d1658da0e0ee6004eb
+  data.tar.gz: e9c96959bc9c30b2684bb4eb13665032753f97463f11192b66f2c5592bbe66c29a49663d1fa4a11b2dc64493d10b462dc24b6a6b2380899467df68cdac26ccae

data/lib/gitlab/experiment/base_interface.rb

@@ -81,7 +81,7 @@ module Gitlab
       def process_redirect_url(url)
         return unless Configuration.redirect_url_validator&.call(url)
 
-        track('visited', url: url)
+        track('visited', url:)
         url # return the url, which allows for mutation
       end
 

data/lib/gitlab/experiment/cache.rb

@@ -43,18 +43,18 @@ module Gitlab
         @cache ||= Interface.new(self, Configuration.cache)
       end
 
-      def cache_variant(specified = nil, &block)
+      def cache_variant(specified = nil, &)
         return (specified.presence || yield) unless cache.store
 
-        result = migrated_cache_fetch(cache.store) || find_variant(&block)
+        result = migrated_cache_fetch(cache.store) || find_variant(&)
         return result unless specified.present?
 
         cache.write(specified) if result.to_s != specified.to_s
         specified
       end
 
-      def find_variant(&block)
-        cache.store.fetch(cache_key, &block)
+      def find_variant(&)
+        cache.store.fetch(cache_key, &)
       end
 
       def cache_key(key = nil, suffix: nil)

data/lib/gitlab/experiment/configuration.rb

@@ -141,7 +141,7 @@ module Gitlab
       # access experiment methods, like `name`, `context`, and `signature`.
       @tracking_behavior = lambda do |event, args|
         # An example of using a generic logger to track events:
-        Configuration.logger.info("#{self.class.name}[#{name}] #{event}: #{args.merge(signature: signature)}")
+        Configuration.logger.info("#{self.class.name}[#{name}] #{event}: #{args.merge(signature:)}")
 
         # Using something like snowplow to track events (in gitlab):
         #
@@ -173,7 +173,7 @@ module Gitlab
       #   level1 initiated by file_name.rb:2
       #   level2 initiated by file_name.rb:3
       @nested_behavior = lambda do |nested_experiment|
-        raise NestingError.new(experiment: self, nested_experiment: nested_experiment)
+        raise NestingError.new(experiment: self, nested_experiment:)
       end
 
       # Called at the end of every experiment run, with the result.

data/lib/gitlab/experiment/context.rb

@@ -49,7 +49,7 @@ module Gitlab
       end
 
       def signature
-        @signature ||= { key: key, migration_keys: migration_keys }.compact
+        @signature ||= { key:, migration_keys: }.compact
       end
 
       def method_missing(method_name, *)

data/lib/gitlab/experiment/cookies.rb

@@ -22,7 +22,7 @@ module Gitlab
         return hash.merge(key => cookie) if hash[key].nil?
 
         add_unmerged_migration(key => cookie)
-        cookie_jar.delete(cookie_name, domain: domain)
+        cookie_jar.delete(cookie_name, domain:)
 
         hash
       end
@@ -32,7 +32,7 @@ module Gitlab
 
         cookie ||= SecureRandom.uuid
         cookie_jar.permanent.signed[cookie_name] = {
-          value: cookie, secure: Configuration.secure_cookie, domain: domain, httponly: true
+          value: cookie, secure: Configuration.secure_cookie, domain:, httponly: true
         }
 
         hash.merge(key => cookie)

data/lib/gitlab/experiment/rspec.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'active_support/core_ext/enumerable'
+require 'active_support/core_ext/object/blank'
+
 module Gitlab
   class Experiment
     module TestBehaviors
@@ -24,7 +27,7 @@ module Gitlab
       end
 
       module MethodDouble
-        def proxy_method_invoked(receiver, *args, &block)
+        def proxy_method_invoked(receiver, *args, &)
           RSpecMocks.track_gitlab_experiment_receiver(original_method, receiver)
           super
         end
@@ -121,6 +124,38 @@ module Gitlab
       end
     end
 
+    # Records experiment tracking calls captured via Configuration.tracking_behavior, so the
+    # `have_tracked_experiment` matcher can assert on the ordered sequence of emitted events. Only
+    # GLEX-native data is captured (the action plus the experiment's signature), so it works for any
+    # consumer regardless of how the host application wires up tracking.
+    class TrackedExperiments
+      attr_reader :events
+
+      def initialize(max_segmentations = 1)
+        @events = []
+        @max_segmentations = max_segmentations
+      end
+
+      def record(action, signature)
+        event = { action: }.merge(signature)
+        verify_single_assignment(event)
+        @events << event
+      end
+
+      private
+
+      def verify_single_assignment(event)
+        return unless event[:action] == :assignment && event[:key].present?
+
+        keys = @events.select { |e| e[:action] == :assignment && e[:key].present? }
+          .pluck(:key).push(event[:key]).uniq
+        return unless keys.size > @max_segmentations
+
+        raise "#{event[:experiment]} was segmented #{keys.size} " \
+          "#{keys.size == 1 ? 'time' : 'times'} (expected #{@max_segmentations}) - #{keys.join(', ')}."
+      end
+    end
+
     module RSpecMatchers
       extend RSpec::Matchers::DSL
 
@@ -135,6 +170,10 @@ module Gitlab
         experiment
       end
 
+      def tracked_experiments
+        @_tracked_experiments
+      end
+
       matcher :register_behavior do |behavior_name|
         match do |experiment|
           @experiment = require_experiment(experiment, 'register_behavior')
@@ -262,7 +301,7 @@ module Gitlab
         chain(:on_next_instance) { @on_next_instance = true }
 
         def set_expectations(event, *event_args, negated:)
-          failure_message = failure_message_with_details(event, negated: negated)
+          failure_message = failure_message_with_details(event, negated:)
           expectations = proc do |e|
             allow(e).to receive(:track).and_call_original
 
@@ -306,6 +345,43 @@ module Gitlab
           details.unshift(base).join("\n")
         end
       end
+
+      matcher :have_tracked_experiment do |experiment_name, expectation = []|
+        match do
+          @experiment_name = experiment_name
+          @expectation = expectation
+
+          expectation == formatted_events
+        end
+
+        failure_message do
+          "Expected to track ordered events:\n#{events_to_s(@expectation)}\n" \
+            "but tracked:\n#{events_to_s(formatted_events)}"
+        end
+
+        def formatted_events
+          unless tracked_experiments
+            raise 'have_tracked_experiment requires the :experiment_tracking metadata tag on the example'
+          end
+
+          tracked_experiments.events
+            .select { |event| event[:experiment] == @experiment_name.to_s }
+            .uniq { |event| event[:action] }
+            .map.with_index { |event, index| format_event(event, @expectation[index] || {}) }
+        end
+
+        # A bare expectation entry (eg. `:assignment`) asserts only the action; a Hash entry (eg.
+        # `{ action: :assignment, migration_keys: [...] }`) asserts each named signature field.
+        def format_event(event, expected_event)
+          return event[:action] unless expected_event.is_a?(Hash)
+
+          expected_event.keys.index_with { |key| event[key] }
+        end
+
+        def events_to_s(events)
+          events.map { |event| "   #{event}" }.join(",\n")
+        end
+      end
     end
   end
 end
@@ -326,6 +402,26 @@ RSpec.configure do |config|
 
   config.include Gitlab::Experiment::RSpecMatchers, :experiment
   config.include Gitlab::Experiment::RSpecMatchers, type: :experiment
+  config.include Gitlab::Experiment::RSpecMatchers, :experiment_tracking
+
+  # Capture experiment tracking calls at the gem's own emission seam (Configuration.tracking_behavior),
+  # so `have_tracked_experiment` can assert on them without coupling to any host tracking implementation.
+  # The metadata value, when numeric, sets the maximum number of segmentations allowed (defaults to 1).
+  config.before(:each, :experiment_tracking) do |example|
+    max_segmentations = example.metadata[:experiment_tracking]
+    max_segmentations = 1 unless max_segmentations.is_a?(Numeric)
+    recorder = @_tracked_experiments = Gitlab::Experiment::TrackedExperiments.new(max_segmentations)
+
+    @_original_tracking_behavior = Gitlab::Experiment::Configuration.tracking_behavior
+    Gitlab::Experiment::Configuration.tracking_behavior = lambda do |action, _args|
+      # `instance_exec`'d on the experiment by `Experiment#track`, so `signature` is in scope here.
+      recorder.record(action, signature)
+    end
+  end
+
+  config.after(:each, :experiment_tracking) do
+    Gitlab::Experiment::Configuration.tracking_behavior = @_original_tracking_behavior
+  end
 
   config.define_derived_metadata(file_path: Regexp.new('spec/experiments/')) do |metadata|
     metadata[:type] ||= :experiment

data/lib/gitlab/experiment/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   class Experiment
-    VERSION = '1.5.0'
+    VERSION = '1.6.0'
   end
 end

data/lib/gitlab/experiment.rb

@@ -33,16 +33,16 @@ module Gitlab
     class << self
       # Class level behavior registration methods.
 
-      def control(*filter_list, **options, &block)
-        variant(:control, *filter_list, **options, &block)
+      def control(*filter_list, **options, &)
+        variant(:control, *filter_list, **options, &)
       end
 
-      def candidate(*filter_list, **options, &block)
-        variant(:candidate, *filter_list, **options, &block)
+      def candidate(*filter_list, **options, &)
+        variant(:candidate, *filter_list, **options, &)
       end
 
-      def variant(variant, *filter_list, **options, &block)
-        build_behavior_callback(filter_list, variant, **options, &block)
+      def variant(variant, *filter_list, **options, &)
+        build_behavior_callback(filter_list, variant, **options, &)
       end
 
       # Class level callback registration methods.
@@ -86,12 +86,12 @@ module Gitlab
       [Configuration.name_prefix, @_name].compact.join('_')
     end
 
-    def control(&block)
-      variant(:control, &block)
+    def control(&)
+      variant(:control, &)
     end
 
-    def candidate(&block)
-      variant(:candidate, &block)
+    def candidate(&)
+      variant(:candidate, &)
     end
 
     def variant(name, &block)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-09 00:00:00.000000000 Z
+date: 2026-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -246,7 +246,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="