gitlab-experiment 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31e4979de3006211bcd1f63882215ae9213c3a22de25e7cca8546f3fce2ef649
-  data.tar.gz: cb865da8c87f019755194c98e073720f5f246b5a2c57e6d511c2a280d78ff996
+  metadata.gz: 0d1ad31e8b977491ccdd1a9d21fc348482d3942c80a3e2935a6ccabc515b4243
+  data.tar.gz: bdf9a4b67bb2b5a72931c081fed88ac246853a2e90f4f7f5c08bf7bdb9d8f55e
 SHA512:
-  metadata.gz: 7906faeb21deaa6e0be322c94c0fd45ea200b5419ac5aacd2d2656b416ac08c21654e84f0ef3d2db5bb33c819dc73020267488a6f7f1ac045b66591ec04ae334
-  data.tar.gz: e0f9328d5c8f1eca74681e749e01cc6ccf513d619b3c4aa522c45d08a4692d370a96d97437975285fa26dcebad0a7e0a3a8356724b980902ba1b86c8fa82f0a1
+  metadata.gz: dc1cc5077144d4e5514b6804599bba8e6829ad6472e5e362cde88940995b174f9989733fea17da91be92dc172694a4394ee0db7974efba8d6eb4e77e769a57ee
+  data.tar.gz: 958cf74fa36b1588fd7f83776e87c7f8c92120cb8a6d421c09a4bd207adffdfcfe69ea295dd1e6a49d371225988f6fde3f559baf64d755a0c9176a33e7efddca

data/README.md

@@ -423,6 +423,30 @@ Gitlab::Experiment.configure do |config|
 end
 ```
 
+### Middleware
+
+There are times when you'll need to do link tracking in email templates, or markdown content -- or other places you won't be able to implement tracking. For these cases, gitlab-experiment comes with middleware that will redirect to a given URL while also tracking that the URL was visited.
+
+In Rails this middleware is mounted automatically, with a base path of what's been configured for `mount_at`. If this path is empty the middleware won't be mounted at all.
+
+Once mounted, the redirect URLs can be generated using the Rails route helpers. If not using Rails, mount the middleware and generate these URLs yourself.
+
+```ruby
+Gitlab::Experiment.configure do |config|
+  config.mount_at = '/experiment'
+end
+
+ex = experiment(:example, foo: :bar)
+
+# using rails path/url helpers 
+experiment_redirect_path(ex, 'https//docs.gitlab.com/') # => /experiment/example:[context_key]?https//docs.gitlab.com/
+
+# manually
+"#{Gitlab::Experiment.configure.mount_at}/#{ex.to_param}?https//docs.gitlab.com/"
+```
+
+URLS that match the base path will be handled by the middleware and will redirect to the provided redirect path.
+
 ## Testing (rspec support)
 
 This gem comes with some rspec helpers and custom matchers. These are in flux at the time of writing.

data/lib/generators/gitlab/experiment/install/templates/initializer.rb.tt

@@ -18,8 +18,10 @@ Gitlab::Experiment.configure do |config|
   # The domain to use on cookies.
   #
   # When not set, it uses the current host. If you want to provide specific
-  # hosts, you use `:all`, or provide an array like
-  # `['www.gitlab.com', '.gitlab.com']`.
+  # hosts, you use `:all`, or provide an array.
+  #
+  # Examples:
+  #   nil, :all, or ['www.gitlab.com', '.gitlab.com']
   config.cookie_domain = :all
 
   # The default rollout strategy that works for single and multi-variants.
@@ -28,8 +30,31 @@ Gitlab::Experiment.configure do |config|
   # experiment.
   #
   # Examples include:
-  #   Rollout::First, Rollout::Random, Rollout::RoundRobin
-  config.default_rollout = Gitlab::Experiment::Rollout::First
+  #   Rollout::Random, or Rollout::RoundRobin
+  config.default_rollout = Gitlab::Experiment::Rollout::Percent
+
+  # Secret seed used in generating context keys.
+  #
+  # Consider not using one that's shared with other systems, like Rails'
+  # SECRET_KEY_BASE. Generate a new secret and utilize that instead.
+  @context_key_secret = nil
+
+  # Bit length used by SHA2 in generating context keys.
+  #
+  # Using a higher bit length would require more computation time.
+  #
+  # Valid bit lengths:
+  #   256, 384, or 512.
+  @context_key_bit_length = 256
+
+  # The default base path that the middleware (or rails engine) will be
+  # mounted. Can be nil if you don't want anything to be mounted automatically.
+  #
+  # This enables a similar behavior to how links are instrumented in emails.
+  #
+  # Examples:
+  #   '/-/experiment', '/redirect', nil
+  config.mount_at = '/experiment'
 
   # Logic this project uses to determine inclusion in a given experiment.
   #
@@ -80,17 +105,4 @@ Gitlab::Experiment.configure do |config|
     #
     # Lograge::Event.log(experiment: name, result: result, signature: signature)
   end
-
-  # Algorithm that consistently generates a hash key for a given hash map.
-  #
-  # Given a specific context hash map, we need to generate a consistent hash
-  # key. The logic in here will be used for generating cache keys, and may also
-  # be used when determining which variant may be presented.
-  #
-  # This block is executed within the scope of the experiment and so can access
-  # experiment methods, like `name`, `context`, and `signature`.
-  config.context_hash_strategy = lambda do |context|
-    values = context.values.map { |v| (v.respond_to?(:to_global_id) ? v.to_global_id : v).to_s }
-    Digest::MD5.hexdigest((context.keys + values).join('|'))
-  end
 end

data/lib/gitlab/experiment.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'scientist'
+require 'request_store'
 require 'active_support/callbacks'
 require 'active_support/cache'
 require 'active_support/concern'
@@ -8,6 +9,7 @@ require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/string/inflections'
 require 'active_support/core_ext/module/delegation'
 
+require 'gitlab/experiment/errors'
 require 'gitlab/experiment/base_interface'
 require 'gitlab/experiment/cache'
 require 'gitlab/experiment/callbacks'
@@ -16,6 +18,7 @@ require 'gitlab/experiment/configuration'
 require 'gitlab/experiment/cookies'
 require 'gitlab/experiment/context'
 require 'gitlab/experiment/dsl'
+require 'gitlab/experiment/middleware'
 require 'gitlab/experiment/variant'
 require 'gitlab/experiment/version'
 require 'gitlab/experiment/engine' if defined?(Rails::Engine)
@@ -27,10 +30,26 @@ module Gitlab
     include Callbacks
 
     class << self
-      def default_rollout(rollout = nil)
+      def default_rollout(rollout = nil, options = {})
         return @rollout ||= Configuration.default_rollout if rollout.blank?
 
-        @rollout = Rollout.resolve(rollout)
+        @rollout = Rollout.resolve(rollout).new(options)
+      end
+
+      def exclude(*filter_list, **options, &block)
+        build_callback(:exclusion_check, filter_list.unshift(block), **options) do |target, callback|
+          throw(:abort) if target.instance_variable_get(:@excluded) || callback.call(target, nil) == true
+        end
+      end
+
+      def segment(*filter_list, variant:, **options, &block)
+        build_callback(:segmentation_check, filter_list.unshift(block), **options) do |target, callback|
+          target.variant(variant) if target.instance_variable_get(:@variant_name).nil? && callback.call(target, nil)
+        end
+      end
+
+      def published_experiments
+        RequestStore.store[:published_gitlab_experiments] || {}
       end
     end
 
@@ -38,14 +57,16 @@ module Gitlab
       [Configuration.name_prefix, @name].compact.join('_')
     end
 
-    def use(&block)
-      try(:control, &block)
+    def control(&block)
+      candidate(:control, &block)
     end
+    alias_method :use, :control
 
-    def try(name = nil, &block)
+    def candidate(name = nil, &block)
       name = (name || :candidate).to_s
       behaviors[name] = block
     end
+    alias_method :try, :candidate
 
     def context(value = nil)
       return @context if value.blank?
@@ -59,12 +80,8 @@ module Gitlab
       return Variant.new(name: (@variant_name || :unresolved).to_s) if @variant_name || @resolving_variant
 
       if enabled?
-        @variant_name ||= :control if excluded?
-
         @resolving_variant = true
-        if (result = cache_variant(@variant_name) { resolve_variant_name }).present?
-          @variant_name = result.to_sym
-        end
+        @variant_name = cached_variant_resolver(@variant_name)
       end
 
       run_callbacks(segmentation_callback_chain) do
@@ -75,18 +92,26 @@ module Gitlab
       @resolving_variant = false
     end
 
-    def rollout(rollout = nil)
-      return @rollout ||= self.class.default_rollout if rollout.blank?
+    def rollout(rollout = nil, options = {})
+      return @rollout ||= self.class.default_rollout(nil, options) if rollout.blank?
 
-      @rollout = Rollout.resolve(rollout)
+      @rollout = Rollout.resolve(rollout).new(options)
+    end
+
+    def exclude!
+      @excluded = true
     end
 
     def run(variant_name = nil)
       @result ||= super(variant(variant_name).name)
+    rescue Scientist::BehaviorMissing => e
+      raise Error, e
     end
 
     def publish(result)
       instance_exec(result, &Configuration.publishing_behavior)
+
+      (RequestStore.store[:published_gitlab_experiments] ||= {})[name] = signature.merge(excluded: excluded?)
     end
 
     def track(action, **event_args)
@@ -102,8 +127,7 @@ module Gitlab
     def excluded?
       return @excluded if defined?(@excluded)
 
-      @excluded = !@context.trackable? || # adhere to DNT headers
-        !run_callbacks(:exclusion_check) { :not_excluded } # didn't pass exclusion check
+      @excluded = !run_callbacks(:exclusion_check) { :not_excluded }
     end
 
     def experiment_group?
@@ -111,27 +135,41 @@ module Gitlab
     end
 
     def should_track?
-      enabled? && !excluded?
+      enabled? && @context.trackable? && !excluded?
     end
 
     def signature
       { variant: variant.name, experiment: name }.merge(context.signature)
     end
 
-    def key_for(hash)
-      instance_exec(hash, &Configuration.context_hash_strategy)
+    def key_for(source, seed = name)
+      # TODO: Added deprecation in release 0.6.0
+      if (block = Configuration.instance_variable_get(:@__context_hash_strategy))
+        return instance_exec(source, seed, &block)
+      end
+
+      source = source.keys + source.values if source.is_a?(Hash)
+
+      ingredients = Array(source).map { |v| identify(v) }
+      ingredients.unshift(seed).unshift(Configuration.context_key_secret)
+
+      Digest::SHA2.new(Configuration.context_key_bit_length).hexdigest(ingredients.join('|'))
     end
 
     protected
 
+    def identify(object)
+      (object.respond_to?(:to_global_id) ? object.to_global_id : object).to_s
+    end
+
     def segmentation_callback_chain
-      return :segmentation_check if !variant_assigned? && enabled? && !excluded?
+      return :segmentation_check if @variant_name.nil? && enabled? && !excluded?
 
       :unsegmented
     end
 
     def resolve_variant_name
-      rollout.new(self).execute if experiment_group?
+      rollout.rollout_for(self) if experiment_group?
     end
   end
 end

data/lib/gitlab/experiment/base_interface.rb

@@ -4,13 +4,9 @@ module Gitlab
   class Experiment
     module BaseInterface
       extend ActiveSupport::Concern
-
-      # don't `include` here so we don't override the default scientist class
-      Scientist::Experiment.send(:append_features, self) # rubocop:disable GitlabSecurity/PublicSend
+      include Scientist::Experiment
 
       class_methods do
-        include Scientist::Experiment::RaiseOnMismatch
-
         def configure
           yield Configuration
         end
@@ -30,6 +26,11 @@ module Gitlab
 
           experiment_name(name).classify.safe_constantize || Configuration.base_class.constantize
         end
+
+        def from_param(id)
+          %r{/?(?<name>.*):(?<key>.*)$} =~ id
+          Gitlab::Experiment.new(name).tap { |e| e.context.key(key) }
+        end
       end
 
       def initialize(name = nil, variant_name = nil, **context)
@@ -49,9 +50,10 @@ module Gitlab
       end
 
       def id
-        "#{name}:#{key_for(context.value)}"
+        "#{name}:#{context.key}"
       end
       alias_method :session_id, :id
+      alias_method :to_param, :id
 
       def flipper_id
         "Experiment;#{id}"
@@ -72,8 +74,15 @@ module Gitlab
 
       protected
 
-      def variant_assigned?
-        !@variant_name.nil?
+      def raise_on_mismatches?
+        false
+      end
+
+      def cached_variant_resolver(provided_variant)
+        return :control if excluded?
+
+        result = cache_variant(provided_variant) { resolve_variant_name }
+        result.to_sym if result.present?
       end
 
       def generate_result(variant_name)

data/lib/gitlab/experiment/callbacks.rb

@@ -15,28 +15,17 @@ module Gitlab
       end
 
       class_methods do
-        def exclude(*filter_list, **options, &block)
-          filters = filter_list.unshift(block).compact.map do |filter|
-            result_lambda = ActiveSupport::Callbacks::CallTemplate.build(filter, self).make_lambda
-            lambda do |target|
-              throw(:abort) if target.instance_variable_get(:'@excluded') || result_lambda.call(target, nil) == true
-            end
-          end
-
-          raise ArgumentError, 'no filters provided' if filters.empty?
-
-          set_callback(:exclusion_check, :before, *filters, options)
-        end
+        private
 
-        def segment(*filter_list, variant:, **options, &block)
-          filters = filter_list.unshift(block).compact.map do |filter|
+        def build_callback(chain, filters, **options)
+          filters = filters.compact.map do |filter|
             result_lambda = ActiveSupport::Callbacks::CallTemplate.build(filter, self).make_lambda
-            ->(target) { target.variant(variant) if !target.variant_assigned? && result_lambda.call(target, nil) }
+            ->(target) { yield(target, result_lambda) }
           end
 
           raise ArgumentError, 'no filters provided' if filters.empty?
 
-          set_callback(:segmentation_check, :before, *filters, options)
+          set_callback(chain, *filters, **options)
         end
       end
     end

data/lib/gitlab/experiment/configuration.rb

@@ -26,8 +26,20 @@ module Gitlab
       # The domain to use on cookies.
       @cookie_domain = :all
 
-      # The default rollout strategy that works for single and multi-variants.
-      @default_rollout = Rollout::First
+      # The default rollout strategy only works for single variant experiments.
+      # It's expected that you use a more advanced rollout for multiple variant
+      # experiments.
+      @default_rollout = Rollout::Base.new
+
+      # Secret seed used in generating context keys.
+      @context_key_secret = nil
+
+      # Bit length used by SHA2 in generating context keys - (256, 384 or 512.)
+      @context_key_bit_length = 256
+
+      # The default base path that the middleware (or rails engine) will be
+      # mounted.
+      @mount_at = '/experiment'
 
       # Logic this project uses to determine inclusion in a given experiment.
       # Expected to return a boolean value.
@@ -45,23 +57,24 @@ module Gitlab
         track(:assignment)
       end
 
-      # Algorithm that consistently generates a hash key for a given hash map.
-      @context_hash_strategy = lambda do |hash_map|
-        values = hash_map.values.map { |v| (v.respond_to?(:to_global_id) ? v.to_global_id : v).to_s }
-        Digest::MD5.hexdigest(([name] + hash_map.keys + values).join('|'))
-      end
-
       class << self
+        # TODO: Added deprecation in release 0.6.0
+        def context_hash_strategy=(block)
+          ActiveSupport::Deprecation.warn('context_hash_strategy has been deprecated, instead configure' \
+            ' `context_key_secret` and `context_key_bit_length`.')
+          @__context_hash_strategy = block
+        end
+
         # TODO: Added deprecation in release 0.5.0
         def variant_resolver
           ActiveSupport::Deprecation.warn('variant_resolver is deprecated, instead use `inclusion_resolver` with a' \
-            'block that returns a boolean.')
+            ' block that returns a boolean.')
           @inclusion_resolver
         end
 
         def variant_resolver=(block)
           ActiveSupport::Deprecation.warn('variant_resolver is deprecated, instead use `inclusion_resolver` with a' \
-            'block that returns a boolean.')
+            ' block that returns a boolean.')
           @inclusion_resolver = block
         end
 
@@ -71,11 +84,13 @@ module Gitlab
           :base_class,
           :cache,
           :cookie_domain,
+          :context_key_secret,
+          :context_key_bit_length,
+          :mount_at,
           :default_rollout,
           :inclusion_resolver,
           :tracking_behavior,
-          :publishing_behavior,
-          :context_hash_strategy
+          :publishing_behavior
         )
       end
     end

data/lib/gitlab/experiment/context.rb

@@ -31,6 +31,12 @@ module Gitlab
         @value.merge!(process_migrations(value))
       end
 
+      def key(key = nil)
+        return @key || @experiment.key_for(value) if key.nil?
+
+        @key = key
+      end
+
       def trackable?
         !(@request && @request.headers['DNT'].to_s.match?(DNT_REGEXP))
       end
@@ -41,7 +47,7 @@ module Gitlab
       end
 
       def signature
-        @signature ||= { key: @experiment.key_for(@value), migration_keys: migration_keys }.compact
+        @signature ||= { key: key, migration_keys: migration_keys }.compact
       end
 
       def method_missing(method_name, *)

data/lib/gitlab/experiment/engine.rb

@@ -15,7 +15,21 @@ module Gitlab
         ActionMailer::Base.helper_method(:experiment)
       end
 
+      def add_middleware(app, base_path)
+        return if base_path.blank?
+
+        app.config.middleware.use(Middleware, base_path)
+        app.routes.append do
+          direct :experiment_redirect do |experiment, to_url|
+            [base_path, experiment.to_param].join('/') + "?#{to_url}"
+          end
+        end
+      end
+
       config.after_initialize { include_dsl }
+      initializer 'gitlab_experiment.add_middleware' do |app|
+        add_middleware(app, Configuration.mount_at)
+      end
     end
   end
 end

data/lib/gitlab/experiment/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Gitlab
+  class Experiment
+    Error = Class.new(StandardError)
+    InvalidRolloutRules = Class.new(Error)
+  end
+end

data/lib/gitlab/experiment/middleware.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Gitlab
+  class Experiment
+    class Middleware
+      def self.redirect(id, url)
+        raise Error, 'no url to redirect to' if url.blank?
+
+        Gitlab::Experiment.from_param(id).tap { |e| e.track('visited', url: url) }
+        [303, { 'Location' => url }, []]
+      end
+
+      def initialize(app, base_path)
+        @app = app
+        @matcher = %r{^#{base_path}/(?<id>.+)}
+      end
+
+      def call(env)
+        return @app.call(env) if env['REQUEST_METHOD'] != 'GET' || (match = @matcher.match(env['PATH_INFO'])).nil?
+
+        Middleware.redirect(match[:id], env['QUERY_STRING'])
+      rescue Error
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/gitlab/experiment/rollout.rb

@@ -3,7 +3,7 @@
 module Gitlab
   class Experiment
     module Rollout
-      autoload :First, 'gitlab/experiment/rollout/first.rb' # default strategy
+      autoload :Percent, 'gitlab/experiment/rollout/percent.rb'
       autoload :Random, 'gitlab/experiment/rollout/random.rb'
       autoload :RoundRobin, 'gitlab/experiment/rollout/round_robin.rb'
 
@@ -16,10 +16,25 @@ module Gitlab
       class Base
         attr_reader :experiment
 
-        delegate :variant_names, :cache, to: :experiment
+        delegate :variant_names, :cache, :id, to: :experiment
 
-        def initialize(experiment)
+        def initialize(options = {})
+          @options = options
+          # validate! # we want to validate here, but we can't yet
+        end
+
+        def rollout_for(experiment)
           @experiment = experiment
+          validate! # until we have variant registration we can only validate here
+          execute
+        end
+
+        def validate!
+          # base is always valid
+        end
+
+        def execute
+          variant_names.first
         end
       end
     end

data/lib/gitlab/experiment/rollout/percent.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+module Gitlab
+  class Experiment
+    module Rollout
+      class Percent < Base
+        def execute
+          crc = normalized_id
+          total = 0
+
+          case distribution_rules
+          # run through the rules until finding an acceptable one
+          when Array then variant_names[distribution_rules.find_index { |percent| crc % 100 <= total += percent }]
+          # run through the variant names until finding an acceptable one
+          when Hash then distribution_rules.find { |_, percent| crc % 100 <= total += percent }.first
+          # when there are no rules, assume even distribution
+          else variant_names[crc % variant_names.length]
+          end
+        end
+
+        def validate!
+          case distribution_rules
+          when nil then nil
+          when Array, Hash
+            if distribution_rules.length != variant_names.length
+              raise InvalidRolloutRules, "the distribution rules don't match the number of variants defined"
+            end
+          else
+            raise InvalidRolloutRules, 'unknown distribution options type'
+          end
+        end
+
+        private
+
+        def normalized_id
+          Zlib.crc32(id, nil)
+        end
+
+        def distribution_rules
+          @options[:distribution]
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/experiment/rspec.rb

@@ -3,44 +3,78 @@
 module Gitlab
   class Experiment
     module RSpecHelpers
-      def stub_experiments(experiments)
-        experiments.each do |name, variant|
-          variant = :control if variant == false
+      def stub_experiments(experiments, times = nil)
+        experiments.each { |experiment| wrapped_experiment(experiment, times) }
+      end
+
+      def wrapped_experiment(experiment, times = nil, expected = false, &block)
+        klass, experiment_name, variant_name = *experiment_details(experiment)
+        base_klass = Configuration.base_class.constantize
 
-          base = Configuration.base_class.constantize
-          klass = base.constantize(name) || base
+        # Set expectations on experiment classes so we can and_wrap_original with more specific args
+        experiment_klasses = base_klass.descendants.reject { |k| k == klass }
+        experiment_klasses.push(base_klass).each do |k|
+          allow(k).to receive(:new).and_call_original
+        end
 
-          # We have to use this high level any_instance behavior as there's
-          # not an alternative that allows multiple wrappings of `new`.
-          allow_any_instance_of(klass).to receive(:enabled?).and_return(true)
+        receiver = receive(:new)
 
-          if variant == true # passing true allows the rollout to do its job
-            allow_any_instance_of(klass).to receive(:experiment_group?).and_return(true)
-          else
-            allow_any_instance_of(klass).to receive(:resolve_variant_name).and_return(variant.to_s)
+        # Be specific for BaseClass calls
+        receiver = receiver.with(experiment_name, any_args) if experiment_name && klass == base_klass
+
+        receiver.exactly(times).times if times
+
+        # Set expectations on experiment class of interest
+        allow_or_expect_klass = expected ? expect(klass) : allow(klass)
+        allow_or_expect_klass.to receiver.and_wrap_original do |method, *original_args, &original_block|
+          method.call(*original_args).tap do |e|
+            # Stub internal methods before calling the original_block
+            allow(e).to receive(:enabled?).and_return(true)
+
+            if variant_name == true # passing true allows the rollout to do its job
+              allow(e).to receive(:experiment_group?).and_return(true)
+            else
+              allow(e).to receive(:resolve_variant_name).and_return(variant_name.to_s)
+            end
+
+            # Stub/set expectations before calling the original_block
+            yield e if block
+
+            original_block.call(e) if original_block.present?
           end
         end
       end
 
-      def wrapped_experiment(experiment, shallow: false, failure: nil, &block)
-        if shallow
-          yield experiment if block.present?
-          return experiment
-        end
+      private
 
-        receive_wrapped_new = receive(:new).and_wrap_original do |new, *new_args, &new_block|
-          instance = new.call(*new_args)
-          instance.tap(&block) if block.present?
-          instance.tap(&new_block) if new_block.present?
-          instance
+      def experiment_details(experiment)
+        if experiment.is_a?(Symbol)
+          experiment_name = experiment
+          variant_name = nil
         end
 
-        klass = experiment.class == Class ? experiment : experiment.class
-        if failure
-          expect(klass).to receive_wrapped_new, failure
+        experiment_name, variant_name = *experiment if experiment.is_a?(Array)
+
+        base_klass = Configuration.base_class.constantize
+        variant_name = experiment.variant.name if experiment.is_a?(base_klass)
+
+        if experiment.class.name.nil? # Anonymous class instance
+          klass = experiment.class
+        elsif experiment.instance_of?(Class) # Class level stubbing, eg. "MyExperiment"
+          klass = experiment
         else
-          allow(klass).to receive_wrapped_new
+          experiment_name ||= experiment.instance_variable_get(:@name)
+          klass = base_klass.constantize(experiment_name)
         end
+
+        if experiment_name && klass == base_klass
+          experiment_name = experiment_name.to_sym
+
+          # For experiment names like: "group/experiment-name"
+          experiment_name = experiment_name.to_s if experiment_name.inspect.include?('"')
+        end
+
+        [klass, experiment_name, variant_name]
       end
     end
 
@@ -135,34 +169,41 @@ module Gitlab
         end
 
         chain(:with_context) { |expected_context| @expected_context = expected_context }
-        chain(:on_any_instance) { @on_self = false }
+
+        chain(:on_next_instance) { @on_next_instance = true }
 
         def expect_tracking_on(experiment, negated, event, *event_args)
-          @experiment = experiment
-          @on_self = true if require_experiment(experiment, 'track', classes: !@on_self) && @on_self.nil?
-          wrapped_experiment(experiment, shallow: @on_self, failure: failure_message(:no_new, event)) do |instance|
-            @experiment = instance
-            allow(@experiment).to receive(:track)
+          klass = experiment.instance_of?(Class) ? experiment : experiment.class
+          unless klass <= Gitlab::Experiment
+            raise(
+              ArgumentError,
+              "track matcher is limited to experiment instances and classes"
+            )
+          end
+
+          expectations = proc do |e|
+            @experiment = e
+            allow(e).to receive(:track).and_call_original
 
             if negated
-              expect(@experiment).not_to receive_tracking_call_for(event, *event_args)
+              expect(e).not_to receive(:track).with(*[event, *event_args])
             else
-              expect(@experiment).to receive_tracking_call_for(event, *event_args)
-            end
-          end
-        end
+              if @expected_variant
+                expect(@experiment.variant.name).to eq(@expected_variant), failure_message(:variant, event)
+              end
 
-        def receive_tracking_call_for(expected_event, *expected_event_args)
-          receive(:track).with(*[expected_event, *expected_event_args]).and_wrap_original do |track, event, *event_args|
-            track.call(event, *event_args) # call the original
+              if @expected_context
+                expect(@experiment.context.value).to include(@expected_context), failure_message(:context, event)
+              end
 
-            if @expected_variant
-              expect(@experiment.variant.name).to eq(@expected_variant), failure_message(:variant, expected_event)
+              expect(e).to receive(:track).with(*[event, *event_args]).and_call_original
             end
+          end
 
-            if @expected_context
-              expect(@experiment.context.value).to include(@expected_context), failure_message(:context, expected_event)
-            end
+          if experiment.instance_of?(Class) || @on_next_instance
+            wrapped_experiment(experiment, nil, true) { |e| expectations.call(e) }
+          else
+            expectations.call(experiment)
           end
         end
 
@@ -180,8 +221,6 @@ module Gitlab
                   expected context: #{@expected_context}
                     actual context: #{@experiment.context.value}
             MESSAGE
-          when :no_new
-            %(expected #{@experiment.inspect} to have tracked #{event.inspect}, but no new instances were created)
           end
         end
       end
@@ -193,6 +232,10 @@ RSpec.configure do |config|
   config.include Gitlab::Experiment::RSpecHelpers
   config.include Gitlab::Experiment::Dsl
 
+  config.before(:each, :experiment) do
+    RequestStore.clear!
+  end
+
   config.include Gitlab::Experiment::RSpecMatchers, :experiment
   config.define_derived_metadata(file_path: Regexp.new('/spec/experiments/')) do |metadata|
     metadata[:type] = :experiment

data/lib/gitlab/experiment/variant.rb

@@ -2,6 +2,10 @@
 
 module Gitlab
   class Experiment
-    Variant = Struct.new(:name, :payload, keyword_init: true)
+    Variant = Struct.new(:name, :payload, keyword_init: true) do
+      def group
+        name == 'control' ? :control : :experiment
+      end
+    end
   end
 end

data/lib/gitlab/experiment/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   class Experiment
-    VERSION = '0.5.0'
+    VERSION = '0.6.1'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - GitLab
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-03-11 00:00:00.000000000 Z
+date: 2021-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -24,26 +24,40 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: request_store
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: scientist
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.6'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.5.0
+        version: 1.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.6'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.5.0
+        version: 1.6.0
 description: 
 email:
 - gitlab_rubygems@gitlab.com
@@ -74,8 +88,10 @@ files:
 - lib/gitlab/experiment/cookies.rb
 - lib/gitlab/experiment/dsl.rb
 - lib/gitlab/experiment/engine.rb
+- lib/gitlab/experiment/errors.rb
+- lib/gitlab/experiment/middleware.rb
 - lib/gitlab/experiment/rollout.rb
-- lib/gitlab/experiment/rollout/first.rb
+- lib/gitlab/experiment/rollout/percent.rb
 - lib/gitlab/experiment/rollout/random.rb
 - lib/gitlab/experiment/rollout/round_robin.rb
 - lib/gitlab/experiment/rspec.rb
@@ -100,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.20
 signing_key: 
 specification_version: 4
 summary: GitLab experiment library built on top of scientist.

data/lib/gitlab/experiment/rollout/first.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module Gitlab
-  class Experiment
-    module Rollout
-      class First < Base
-        # This rollout strategy just picks the first variant name. It's the
-        # default resolver as it assumes a single variant. You should consider
-        # using a more advanced rollout if you have multiple variants.
-        def execute
-          variant_names.first
-        end
-      end
-    end
-  end
-end