gitlab-experiment 1.1.0 → 1.3.0

data/lib/gitlab/experiment/configuration.rb

@@ -44,6 +44,15 @@ module Gitlab
         "#{experiment.name}_id"
       end
 
+      # Allow forced variant assignment via query parameter and cookie.
+      #
+      # When enabled, experiments will check for a `glex_force` query
+      # parameter and a `_glex_force` cookie to override variant assignment.
+      # This is intended for QA/UAT testing in staging and production.
+      #
+      # Defaults to false (disabled).
+      @allow_forced_assignment = false
+
       # Mark experiment cookies as secure (HTTPS only).
       #
       # When set to true, cookies will have the secure flag set, meaning they
@@ -187,6 +196,7 @@ module Gitlab
           :cookie_domain,
           :cookie_name,
           :secure_cookie,
+          :allow_forced_assignment,
           :context_key_secret,
           :context_key_bit_length,
           :mount_at,

data/lib/gitlab/experiment/force_assignment.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Gitlab
+  class Experiment
+    module ForceAssignment
+      PARAM_NAME = 'glex_force'
+
+      private
+
+      def forced_variant_name
+        return unless Configuration.allow_forced_assignment
+        return unless enabled?
+
+        param = context&.request&.params.try(:[], PARAM_NAME)
+        return if param.blank?
+
+        experiment_name, variant_name = param.split(':', 2)
+        return if experiment_name.blank? || variant_name.blank?
+        return unless experiment_name == name
+
+        variant_sym = variant_name.to_sym
+        return unless behaviors.key?(variant_sym)
+
+        variant_sym
+      end
+    end
+  end
+end

data/lib/gitlab/experiment/rspec.rb

@@ -6,7 +6,7 @@ module Gitlab
       autoload :Trackable, 'gitlab/experiment/test_behaviors/trackable.rb'
     end
 
-    WrappedExperiment = Struct.new(:klass, :experiment_name, :variant_name, :expectation_chain, :blocks)
+    WrappedExperiment = Struct.new(:klass, :experiment_name, :variant_name, :expectation_chain, :blocks, :assigned)
 
     module RSpecMocks
       @__gitlab_experiment_receivers = {}
@@ -44,6 +44,12 @@ module Gitlab
               # Call the original method if we specified simply `true`.
               wrapped.variant_name == true ? method.call : wrapped.variant_name
             }
+
+            # Stub find_variant only if caching is not enabled
+            unless Configuration.cache
+              variant_return_value = wrapped.assigned ? wrapped.variant_name.to_s : nil
+              allow(instance).to receive(:find_variant).and_return(variant_return_value)
+            end
           end
         end
 
@@ -51,11 +57,11 @@ module Gitlab
       end
 
       def wrapped_experiment(experiment, remock: false, &block)
-        klass, experiment_name, variant_name = *extract_experiment_details(experiment)
+        klass, experiment_name, variant_name, assigned = *extract_experiment_details(experiment)
 
         wrapped_experiment = wrapped_experiments[experiment_name] =
           (!remock && wrapped_experiments[experiment_name]) ||
-          WrappedExperiment.new(klass, experiment_name, variant_name, wrapped_experiment_chain_for(klass), [])
+          WrappedExperiment.new(klass, experiment_name, variant_name, wrapped_experiment_chain_for(klass), [], assigned)
 
         wrapped_experiment.blocks << block if block
         wrapped_experiment
@@ -84,9 +90,16 @@ module Gitlab
       def extract_experiment_details(experiment)
         experiment_name = nil
         variant_name = nil
-
-        experiment_name = experiment if experiment.is_a?(Symbol)
-        experiment_name, variant_name = *experiment if experiment.is_a?(Array)
+        assigned = nil
+
+        if experiment.is_a?(Array)
+          # From normalize_experiments: [experiment_name, variant_name_or_config]
+          experiment_name, variant_name = *experiment
+          assigned = variant_name.is_a?(Hash) ? variant_name.delete(:assigned) : nil
+          variant_name = variant_name[:variant] if variant_name.is_a?(Hash)
+        elsif experiment.is_a?(Symbol)
+          experiment_name = experiment
+        end
 
         base_klass = Configuration.base_class.constantize
         variant_name = experiment.assigned.name if experiment.is_a?(base_klass)
@@ -94,7 +107,7 @@ module Gitlab
         resolved_klass = experiment_klass(experiment) { base_klass.constantize(experiment_name) }
         experiment_name ||= experiment.instance_variable_get(:@_name)
 
-        [resolved_klass, experiment_name.to_s, variant_name]
+        [resolved_klass, experiment_name.to_s, variant_name, assigned]
       end
 
       def experiment_klass(experiment, &block)

data/lib/gitlab/experiment/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   class Experiment
-    VERSION = '1.1.0'
+    VERSION = '1.3.0'
   end
 end

data/lib/gitlab/experiment.rb

@@ -13,6 +13,7 @@ require 'gitlab/experiment/callbacks'
 require 'gitlab/experiment/rollout'
 require 'gitlab/experiment/configuration'
 require 'gitlab/experiment/cookies'
+require 'gitlab/experiment/force_assignment'
 require 'gitlab/experiment/context'
 require 'gitlab/experiment/dsl'
 require 'gitlab/experiment/middleware'
@@ -26,6 +27,7 @@ module Gitlab
     include BaseInterface
     include Cache
     include Callbacks
+    include ForceAssignment
     include Nestable
 
     class << self
@@ -107,6 +109,8 @@ module Gitlab
     end
 
     def assigned(value = nil)
+      # Skip force assignment if a variant was already set (e.g., via constructor or explicit #assigned call).
+      value ||= forced_variant_name unless @_assigned_variant_name
       @_assigned_variant_name = cache_variant(value) if value.present?
       return Variant.new(name: @_assigned_variant_name || :unresolved) if @_assigned_variant_name || @_resolving_variant
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-27 00:00:00.000000000 Z
+date: 2026-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -223,6 +223,7 @@ files:
 - lib/gitlab/experiment/dsl.rb
 - lib/gitlab/experiment/engine.rb
 - lib/gitlab/experiment/errors.rb
+- lib/gitlab/experiment/force_assignment.rb
 - lib/gitlab/experiment/middleware.rb
 - lib/gitlab/experiment/nestable.rb
 - lib/gitlab/experiment/rollout.rb