gitlab-experiment 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3305c24f350ec02a3ef81da742a6d108c7aef00623f8b2534f989f06ec4a2ba6
-  data.tar.gz: 5f9113235e1623a2012ea5e4c451ed41baeb847e5883951b95b44fd6d7fd40fa
+  metadata.gz: ea78e416b0b830fe748b29e64d0871d4ece35d99bb6c4142fae1a6b1e2bbfb96
+  data.tar.gz: ec16e265a80b00380528ba3d2aee36f1da8ffb13b7941a838dcc73e20671aca4
 SHA512:
-  metadata.gz: d7120d36eb59039dbe36eb728990b951b96b7aa118a0a73af32e18809eaed265d03dec4689b55c3118e14a252418c9c84c4e25f7c25573205c6ef5269e5f456f
-  data.tar.gz: 9233969833c74c432b187721a2b35a38e521fce3679bccf64f879b87c899e6202b0f60b047c5aa57aef10665816f3fd7b3d21f7e403b30424b1227017c9991b2
+  metadata.gz: a767ae547fae832e9053ba91779fc0c1ee85bd16bda1d2a1eb41239fe34a01921b2ef734bea5fbe4724c45f70bed2f3cfbec9c68624d4003c9f30493bf50e99b
+  data.tar.gz: cabbdd641f2ee46db0be4209e28866eb7f5437f46f60ba23c0fe82dfb16944620f360506a7ddad3f17d2fcbf149c374a876545473afc474b943518fbfb631a7f

data/README.md

@@ -669,20 +669,52 @@ end
 
 ### Stub helpers
 
-You can stub experiment variant resolution using the `stub_experiments` helper. Pass a hash of experiment names and the variant each should resolve to.
+You can stub experiment variant resolution using the `stub_experiments` helper. The helper supports multiple formats for
+flexibility:
+
+**Simple hash format:**
 
 ```ruby
-it "stubs experiments to resolve to a specific variant" do
+it "stubs experiments using hash format" do
   stub_experiments(pill_color: :red)
 
   experiment(:pill_color) do |e|
     expect(e).to be_enabled
     expect(e.assigned.name).to eq('red')
   end
-end 
+end
+```
+
+**Hash format with options:**
+
+```ruby
+it "stubs experiments with assigned option" do
+  stub_experiments(pill_color: { variant: :red, assigned: true })
+
+  experiment(:pill_color) do |e|
+    expect(e).to be_enabled
+    expect(e.assigned.name).to eq('red')
+  end
+end
+```
+
+**Mixed formats (symbols and hashes together):**
+
+```ruby
+it "stubs multiple experiments with mixed formats" do
+  stub_experiments(
+    pill_color: :red,
+    hippy: { variant: :free_love, assigned: true },
+    yuppie: :financial_success
+  )
+
+  expect(experiment(:pill_color).assigned.name).to eq(:red)
+  expect(experiment(:hippy).assigned.name).to eq(:free_love)
+  expect(experiment(:yuppie).assigned.name).to eq(:financial_success)
+end
 ```
 
-In special cases you can use a boolean `true` instead of a variant name. This allows the rollout strategy to resolve the variant however it wants to, but is otherwise just making sure the experiment is considered enabled.
+**Boolean true (allows rollout strategy to assign):**
 
 ```ruby
 it "stubs experiments while allowing the rollout strategy to assign the variant" do
@@ -695,30 +727,36 @@ it "stubs experiments while allowing the rollout strategy to assign the variant"
 end
 ```
 
-You can also test the `only_assigned` behavior by stubbing cache states:
+#### Testing `only_assigned` behavior
+
+When you use the `assigned: true` option in `stub_experiments`, the `find_variant` method is automatically stubbed
+to return the specified variant. This allows you to test the `only_assigned` behavior:
 
 ```ruby
-it "tests only_assigned behavior with cached variants" do
-  # Stub a cached variant to exist
-  allow_any_instance_of(Gitlab::Experiment).to receive(:find_variant).and_return('red')
-  
+it "tests only_assigned behavior with a cached variant" do
+  stub_experiments(pill_color: { variant: :red, assigned: true })
+
   experiment_instance = experiment(:pill_color, actor: user, only_assigned: true)
-  
+
   expect(experiment_instance).not_to be_excluded
   expect(experiment_instance.run).to eq('red')
 end
 
-it "tests only_assigned behavior without cached variants" do
-  # Stub no cached variant
-  allow_any_instance_of(Gitlab::Experiment).to receive(:find_variant).and_return(nil)
-  
+it "tests only_assigned behavior without a cached variant" do
+  stub_experiments(pill_color: :red)
+
   experiment_instance = experiment(:pill_color, actor: user, only_assigned: true)
-  
+
   expect(experiment_instance).to be_excluded
-  expect(experiment_instance.run).to eq('blue') # control behavior
+  expect(experiment_instance.run).to eq('red')
 end
 ```
 
+**Note:** The `assigned: true` option only works correctly when caching is disabled. When caching is enabled,
+`find_variant` will attempt to read from the actual cache store rather than using the stub. In this case, you can
+populate the cache naturally by running the experiment first to assign and cache a variant before testing with
+`only_assigned: true`.
+
 ### Registered behaviors matcher
 
 It's useful to test our registered behaviors, as well as their return values when we implement anything complex in them. The `register_behavior` matcher is useful for this. 

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.2.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-27 00:00:00.000000000 Z
+date: 2025-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport