gitlab-experiment 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45c95c2d6d85df98de92096ab00a7cb124ef3cf46f2dfa858465b3c43df8b22d
-  data.tar.gz: 17716054da0e7aff4c67ddea28c733ec275eaf95934d627bbea40856427ecb68
+  metadata.gz: ea78e416b0b830fe748b29e64d0871d4ece35d99bb6c4142fae1a6b1e2bbfb96
+  data.tar.gz: ec16e265a80b00380528ba3d2aee36f1da8ffb13b7941a838dcc73e20671aca4
 SHA512:
-  metadata.gz: a3549e9ec7f899a6994937545c1afcfaceac52efa373b3e7e594b4cd1a08e7df376d1bf79403704d681ea48a29362358ff36fd5cb0fdff6fca29c79c097c0fbb
-  data.tar.gz: 7da4141f53babfa226082190ef4c144900df52a8c1c35d03b1270dd4f3f8c2c1be16aad59a9d2da1e833d0a063177b4212744aad9e6a273637c265ea2148d317
+  metadata.gz: a767ae547fae832e9053ba91779fc0c1ee85bd16bda1d2a1eb41239fe34a01921b2ef734bea5fbe4724c45f70bed2f3cfbec9c68624d4003c9f30493bf50e99b
+  data.tar.gz: cabbdd641f2ee46db0be4209e28866eb7f5437f46f60ba23c0fe82dfb16944620f360506a7ddad3f17d2fcbf149c374a876545473afc474b943518fbfb631a7f

data/README.md

@@ -195,7 +195,9 @@ experiment(:pill_color, actor: User.first).run # => "red"
 
 ### Exclusion rules
 
-Exclusion rules let us determine if a context should even be considered as something to include in an experiment. If we're excluding something, it means that we don't want to run the experiment in that case. This can be useful if you only want to run experiments on new users for instance.
+Exclusion rules let us determine if a context should even be considered as something to include in an experiment. If
+we're excluding something, it means that we don't want to run the experiment in that case. This can be useful if you
+only want to run experiments on new users for instance.
 
 ```ruby
 class PillColorExperiment < Gitlab::Experiment # OR ApplicationExperiment
@@ -205,15 +207,40 @@ class PillColorExperiment < Gitlab::Experiment # OR ApplicationExperiment
 end
 ```
 
-In the previous example, we'll exclude all users named `'Richard'` as well as any account older than 2 weeks old. Not only will they be immediately given the control behavior, but no events will be tracked in these cases either.
+In the previous example, we'll exclude all users named `'Richard'` as well as any account older than 2 weeks old. Not
+only will they be immediately given the control behavior, but no events will be tracked in these cases either.
 
-Exclusion rules are executed in the order they're defined. The first exclusion rule to produce a truthy result will halt execution of further exclusion checks.
+Exclusion rules are executed in the order they're defined. The first exclusion rule to produce a truthy result will halt
+execution of further exclusion checks.
 
-Note: Although tracking calls will be ignored on all exclusions, you may want to check exclusion yourself in expensive custom logic by calling the `should_track?` or `excluded?` methods.
+#### Excluding from within the experiment block
 
-Note: When using exclusion rules it's important to understand that the control assignment is cached, which improves future experiment run performance but can be a gotcha around caching.
+You can also exclude contexts dynamically from within the experiment block using the `exclude!` method. This provides a
+convenient way to include exclusion logic directly within the experiment call:
 
-Note: Exclusion rules aren't the best way to determine if an experiment is enabled. There's an `enabled?` method that can be overridden to have a high-level way of determining if an experiment should be running and tracking at all. This `enabled?` check should be as efficient as possible because it's the first early opt out path an experiment can implement. This can be seen in [How it works](#how-it-works).
+```ruby
+experiment(:pill_color, actor: current_user) do |e|
+  e.exclude! unless can?(current_user, :manage, project)
+
+  e.control { 'blue' }
+  e.candidate { 'red' }
+end
+```
+
+This approach keeps the experiment logic wrapped nicely within the experiment block, rather than requiring you to wrap
+the entire experiment call in conditional logic. When `exclude!` is called, the experiment will be excluded and return
+the control behavior without tracking any events.
+
+Note: Although tracking calls will be ignored on all exclusions, you may want to check exclusion yourself in expensive
+custom logic by calling the `should_track?` or `excluded?` methods.
+
+Note: When using exclusion rules it's important to understand that the control assignment is cached, which improves
+future experiment run performance but can be a gotcha around caching.
+
+Note: Exclusion rules aren't the best way to determine if an experiment is enabled. There's an `enabled?` method that
+can be overridden to have a high-level way of determining if an experiment should be running and tracking at all. This
+`enabled?` check should be as efficient as possible because it's the first early opt out path an experiment can
+implement. This can be seen in [How it works](#how-it-works).
 
 ### Segmentation rules
 
@@ -642,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
 ```
 
-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.
+**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
+```
+
+**Boolean true (allows rollout strategy to assign):**
 
 ```ruby
 it "stubs experiments while allowing the rollout strategy to assign the variant" do
@@ -668,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. 
@@ -770,7 +835,14 @@ Each of these approaches could be desirable given the objectives of your experim
 
 After cloning the repo, run `bundle install` to install dependencies.
 
-Run `bundle exec rake` to run the tests. You can also run `bundle exec pry` for an interactive prompt that will allow you to experiment.
+## Running tests
+
+The test suite requires Redis to be running. [Install](https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis/) and start Redis (`redis-server`) before running tests. 
+
+Once Redis is running, execute the tests:
+`bundle exec rake`
+
+You can also run `bundle exec pry` for an interactive prompt that will allow you to experiment.
 
 ## Contributing
 

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

@@ -31,6 +31,14 @@ Gitlab::Experiment.configure do |config|
   #   nil, :all, or ['www.gitlab.com', '.gitlab.com']
   config.cookie_domain = :all
 
+  # Mark experiment cookies as secure (HTTPS only).
+  #
+  # When set to true, cookies will have the secure flag set, meaning they
+  # will only be sent over HTTPS connections. Defaults to true.
+  #
+  # Set to false in development/test environments if needed:
+  #   config.secure_cookie = Rails.env.production?
+
   # The default rollout strategy.
   #
   # The recommended default rollout strategy when not using caching would

data/lib/generators/rspec/experiment/templates/experiment_spec.rb.tt

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'rails_helper'
+require 'spec_helper'
 
 <% module_namespacing do -%>
 RSpec.describe <%= class_name %>Experiment do

data/lib/gitlab/experiment/configuration.rb

@@ -44,6 +44,15 @@ module Gitlab
         "#{experiment.name}_id"
       end
 
+      # Mark experiment cookies as secure (HTTPS only).
+      #
+      # When set to true, cookies will have the secure flag set, meaning they
+      # will only be sent over HTTPS connections. Defaults to true.
+      #
+      # Set to false in development/test environments if needed:
+      #   config.secure_cookie = Rails.env.production?
+      @secure_cookie = true
+
       # The default rollout strategy.
       #
       # The recommended default rollout strategy when not using caching would
@@ -177,6 +186,7 @@ module Gitlab
           :cache,
           :cookie_domain,
           :cookie_name,
+          :secure_cookie,
           :context_key_secret,
           :context_key_bit_length,
           :mount_at,

data/lib/gitlab/experiment/cookies.rb

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

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.0.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.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-29 00:00:00.000000000 Z
+date: 2025-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport