gitlab-experiment 0.4.5 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81476752521c6ead83308324fdcf360db7b8182bab340c9ffe7ad4eec21b998e
-  data.tar.gz: 006d94ff92104bef820be7d6c7c9638b20a6e0a4a533439fca056b4cba31a0bc
+  metadata.gz: 51c0f257bd0cea5fa7b970e764ac5cce9f24c5a844673f05579d1c902a46fc39
+  data.tar.gz: ddd93dc46cdde532f20edd5209651d511105157ee9dd13d58c5a60cb229cd3ca
 SHA512:
-  metadata.gz: a5644f3cf6798ddc27034b8857cf03bb77904b3b5c8a80b84c398134ad143b919e16ddc23746a58e63b71d0464c92ec5cce682ddb2039e471b55cfeb42e3cd4a
-  data.tar.gz: 2dd2adf62427f96a9745d9681ee87b5621acf43fc4dae33ffefdadfad5af6ec3a0ad1e79e601a4d6260e61fa64faf635af9ae753e3fb474e033af7d2d7d55381
+  metadata.gz: 243606b6b55ebe069296c564ad801a6b25075a85d2b2ca38eb47e836b75b655fa9472fbcf0a0cb01c83093b97d529f8b2aec04389d79119064b5021c975b0042
+  data.tar.gz: 1900d8b44458d2cf1e2086cc48d5e3ccc19160926c1dc9b827b7a93d042edf7354e1eeb35cae12e0c33f133aef39f605dbd5446edf987c1d99a38264d3b97d72

data/README.md

@@ -100,6 +100,9 @@ Here are some examples of what you can introduce once you have a custom experime
 
 ```ruby
 class NotificationToggleExperiment < ApplicationExperiment
+  # Exclude any users that aren't me.
+  exclude :all_but_me
+
   # Segment any account less than 2 weeks old into the candidate, without
   # asking the variant resolver to decide which variant to provide.
   segment :account_age, variant: :candidate
@@ -107,17 +110,21 @@ class NotificationToggleExperiment < ApplicationExperiment
   # Define the default control behavior, which can be overridden at
   # experiment time.
   def control_behavior
-    render_toggle
+    # render_toggle
   end
 
   # Define the default candidate behavior, which can be overridden
   # at experiment time.
   def candidate_behavior
-    render_button
+    # render_button
   end
 
   private
 
+  def all_but_me
+    context.actor&.username == 'jejacks0n'
+  end
+
   def account_age
     context.actor && context.actor.created_at < 2.weeks.ago
   end
@@ -177,7 +184,7 @@ Generally, defining segmentation rules is a better way to approach routing into
 experiment(:notification_toggle, :no_interface, actor: user) do |e|
   e.use { render_toggle } # control
   e.try { render_button } # candidate
-  e.try(:no_interface) { no_interface! } # variant
+  e.try(:no_interface) { no_interface! } # no_interface variant
 end
 ```
 
@@ -222,6 +229,27 @@ When an experiment is run, the segmentation rules are executed in the order they
 
 This means that any user with the name `'jejacks0n'`, regardless of account age, will always be provided the experience as defined in "variant_one". 
 
+### Exclusion rules
+
+Exclusion rules are similar to segmentation rules, but are intended to determine if a context should even be considered as something we should track events towards. Exclusion means we don't care about the events in relation to the given context. 
+
+```ruby
+class NotificationToggleExperiment < ApplicationExperiment
+  exclude { context.actor.username != 'jejacks0n' }
+  exclude { context.actor.created_at < 2.weeks.ago }
+end
+```
+
+The previous examples will force all users with a username not matching `'jejacks0n'` and all newish users into the control. No events would be tracked for those.
+
+You may need to check exclusion in custom tracking logic, by checking `excluded?` or wrapping your code in a callback block:
+
+```ruby
+run_callbacks(:exclusion_check) do
+  track(:my_event, value: expensive_method_call)
+end
+```
+
 ### Return value
 
 By default the return value is a `Gitlab::Experiment` instance. In simple cases you may want only the results of the experiment though. You can call `run` within the block to get the return value of the assigned variant.

data/lib/gitlab/experiment.rb

@@ -58,11 +58,9 @@ module Gitlab
       raise ArgumentError, 'name is required' if name.blank? && self.class.base?
 
       @name = self.class.experiment_name(name, suffix: false)
-      @excluded = []
       @context = Context.new(self, **context)
       @variant_name = cache_variant(variant_name) { nil } if variant_name.present?
 
-      exclude { !@context.trackable? }
       compare { false }
 
       yield self if block_given?
@@ -81,27 +79,25 @@ module Gitlab
       end
 
       @variant_name = value unless value.blank?
-      @variant_name ||= :control if excluded?
 
-      @resolving_variant = true
-      resolved = :control
-      if (result = cache_variant(@variant_name) { resolve_variant_name }).present?
-        @variant_name = resolved = result.to_sym
+      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
       end
 
-      Variant.new(name: resolved.to_s)
+      Variant.new(name: (@variant_name || :control).to_s)
     ensure
       @resolving_variant = false
     end
 
-    def exclude(&block)
-      @excluded << block
-    end
-
     def run(variant_name = nil)
       @result ||= begin
         variant_name = variant(variant_name).name
-        run_callbacks(variant_assigned? ? :unsegmented_run : :segmented_run) do
+        run_callbacks(run_with_segmenting? ? :segmented_run : :unsegmented_run) do
           super(@variant_name ||= variant_name)
         end
       end
@@ -112,7 +108,7 @@ module Gitlab
     end
 
     def track(action, **event_args)
-      return if excluded?
+      return unless should_track?
 
       instance_exec(action, event_args, &Configuration.tracking_behavior)
     end
@@ -143,18 +139,6 @@ module Gitlab
       { variant: variant.name, experiment: name }.merge(context.signature)
     end
 
-    def enabled?
-      true
-    end
-
-    def excluded?
-      @excluded.any? { |exclude| exclude.call(self) }
-    end
-
-    def variant_assigned?
-      !@variant_name.nil?
-    end
-
     def id
       "#{name}:#{key_for(context.value)}"
     end
@@ -170,6 +154,27 @@ module Gitlab
 
     protected
 
+    def enabled?
+      true
+    end
+
+    def excluded?
+      @excluded ||= !@context.trackable? || # adhere to DNT headers
+        !run_callbacks(:exclusion_check) { :not_excluded } # didn't pass exclusion check
+    end
+
+    def should_track?
+      enabled? && !excluded?
+    end
+
+    def run_with_segmenting?
+      !variant_assigned? && enabled? && !excluded?
+    end
+
+    def variant_assigned?
+      !@variant_name.nil?
+    end
+
     def resolve_variant_name
       instance_exec(@variant_name, &Configuration.variant_resolver)
     end

data/lib/gitlab/experiment/callbacks.rb

@@ -9,9 +9,23 @@ module Gitlab
       included do
         define_callbacks(:unsegmented_run)
         define_callbacks(:segmented_run)
+        define_callbacks(:exclusion_check, skip_after_callbacks_if_terminated: true)
       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
+
         def segment(*filter_list, variant:, **options, &block)
           filters = filter_list.unshift(block).compact.map do |filter|
             result_lambda = ActiveSupport::Callbacks::CallTemplate.build(filter, self).make_lambda

data/lib/gitlab/experiment/context.rb

@@ -42,6 +42,14 @@ module Gitlab
         @signature ||= { key: @experiment.key_for(@value), migration_keys: migration_keys }.compact
       end
 
+      def method_missing(method_name, *)
+        @value.include?(method_name.to_sym) ? @value[method_name.to_sym] : super
+      end
+
+      def respond_to_missing?(method_name, *)
+        @value.include?(method_name.to_sym) ? true : super
+      end
+
       private
 
       def process_migrations(value)

data/lib/gitlab/experiment/rspec_matchers.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Gitlab
+  class Experiment
+    module RspecMatchers
+      extend RSpec::Matchers::DSL
+
+      matcher :exclude do |context|
+        ivar = :'@excluded'
+
+        match do |experiment|
+          experiment.context(context)
+
+          experiment.instance_variable_set(ivar, nil)
+          !experiment.run_callbacks(:exclusion_check) { :not_excluded }
+        end
+
+        failure_message do
+          %(expected #{context} to be excluded)
+        end
+
+        failure_message_when_negated do
+          %(expected #{context} not to be excluded)
+        end
+      end
+
+      matcher :segment do |context|
+        ivar = :'@variant_name'
+
+        match do |experiment|
+          experiment.context(context)
+
+          experiment.instance_variable_set(ivar, nil)
+          experiment.run_callbacks(:segmented_run)
+
+          @actual = experiment.instance_variable_get(ivar)
+          @expected ? @actual.to_s == @expected.to_s : @actual.present?
+        end
+
+        chain :into do |expected|
+          raise ArgumentError, 'variant name must be provided' if expected.blank?
+
+          @expected = expected.to_s
+        end
+
+        failure_message do
+          %(expected #{context} to be segmented#{message_details})
+        end
+
+        failure_message_when_negated do
+          %(expected #{context} not to be segmented#{message_details})
+        end
+
+        def message_details
+          message = ''
+          message += %(\n    into: #{@expected}) if @expected
+          message += %(\n  actual: #{@actual}) if @actual
+          message
+        end
+      end
+
+      matcher :track do |event, *event_args|
+        match do |experiment|
+          wrapped(experiment) { |instance| expect(instance).to receive_with(event, *event_args) }
+        end
+
+        match_when_negated do |experiment|
+          wrapped(experiment) { |instance| expect(instance).not_to receive_with(event, *event_args) }
+        end
+
+        def wrapped(experiment, &block)
+          allow(experiment.class).to receive(:new).and_wrap_original do |new, *new_args|
+            new.call(*new_args).tap(&block)
+          end
+        end
+
+        def receive_with(*args)
+          receive(:track).with(*args) # rubocop:disable CodeReuse/ActiveRecord
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.define_derived_metadata(file_path: Regexp.new('/spec/experiments/')) do |metadata|
+    metadata[:type] = :experiment
+  end
+
+  config.include Gitlab::Experiment::RspecMatchers, :experiment
+end

data/lib/gitlab/experiment/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   class Experiment
-    VERSION = '0.4.5'
+    VERSION = '0.4.6'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.6
 platform: ruby
 authors:
 - GitLab
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-01-12 00:00:00.000000000 Z
+date: 2021-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -72,6 +72,7 @@ files:
 - lib/gitlab/experiment/cookies.rb
 - lib/gitlab/experiment/dsl.rb
 - lib/gitlab/experiment/engine.rb
+- lib/gitlab/experiment/rspec_matchers.rb
 - lib/gitlab/experiment/variant.rb
 - lib/gitlab/experiment/version.rb
 homepage: https://gitlab.com/gitlab-org/gitlab-experiment