eeny-meeny 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e28ef5a3f25b3acf3e554f578623aab014bc8033
-  data.tar.gz: 017bf53a5cca472993e25c1d09cc514e3a0983b9
+  metadata.gz: 34311644231b710c6ce1e10c5fb6f4410bd4ed5d
+  data.tar.gz: fa951cdb99821c5cd8d0c032d0048875b210193f
 SHA512:
-  metadata.gz: e188c4dd1ceeee62fdd3efc5ab445808d49b34cb75579dbe591c381c6fab73c2206261473ad27d7dd8df3e72ca4d5d86508ef5d97ad8aba2c2661e2dee926b58
-  data.tar.gz: e7f33467b3c326a158405a528e4ca787afc05061fca5e0fa4581a083f00f7523bc9ebbb6bb1e0d36e1274e41d09e712fef0685bc527c4630de6b89bb1d970437
+  metadata.gz: 46a37bb2552e814042c625c3e864073ac4133f295eec99e8a646b4331182060299981b3e8248e7bda8f3c5c2c629ae276a49f0ca9c4290700c22fc840ee0f508
+  data.tar.gz: 03653ee7e0e9eee45bfe2f0efe87e92df72bf7a74d6546dfae2947330eba02e8dd218bb0f070b55967081b7f00be3dd501596b92af8328b65d3c9d150cb5b6f3

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+### 2.0.0 (2016-09-11)
+
+Features:
+
+    - Added helper and route constraint for smoke tests.
+    - Added rake tasks for creating eeny-meeny cookies from the commandline.
+
+Bugfixes:
+
+    - Fixed experiment start_at and end_at logic.
+
+Breaking Changes:
+
+    - Changed the way the gem is configured.
+    - Replaced EenyMeeny::RouteConstraint with EenyMeeny::ExperimentConstraint and EenyMeeny::SmokeTestConstraint.
+
+Other Changes:
+
+    - Changed default cookie expires header from '1.year.from_now' to '1.month.from_now'.
+    - Improve docuemtation.
+
 ### 1.0.0 (2016-07-03)
 
 Features:

data/README.md

@@ -1,5 +1,6 @@
 eeny-meeny
 ==========================
+[![Gem Version](https://badge.fury.io/rb/eeny-meeny.svg)](https://badge.fury.io/rb/eeny-meeny)
 [![Code Climate](https://codeclimate.com/github/corthmann/eeny-meeny/badges/gpa.svg)](https://codeclimate.com/github/corthmann/eeny-meeny)
 [![Test Coverage](https://codeclimate.com/github/corthmann/eeny-meeny/badges/coverage.svg)](https://codeclimate.com/github/corthmann/eeny-meeny/coverage)
 
@@ -20,16 +21,17 @@ Configuration
 
 The following configurations are available:
 
-* `config.eeny_meeny.cookies.path` Defaults to `'/'`. Sets the `path` cookie attribute. If this configuartion is set to `nil` it means that each page will get its own cookie.
-* `config.eeny_meeny.cookies.same_site` Defaults to `:strict`. Accepts: `:strict`, `:lax` and `nil`. Sets the `SameSite` cookie attribute. Selecting `nil` will disable the header on the cookie.
-* `config.eeny_meeny.secure` Boolean value. Defaults to `true` and determines if experiment cookies should be encrypted or not.
-* `config.eeny_meeny.secret` sets the secret used for encrypting experiment cookies.
-* `config.eeny_meeny.experiments` list of experiment-data. It is easiest to load this from a `.yml` file with the following structure:
+* `cookies` Defaults to `{ http_only: true, path: '/', same_site: :strict }`. Sets the eeny-meeny cookie attributes. The valid attributes are listed in the section below.
+* `secure`  Defaults to `true`. Determines if eeny-meeny cookies should be encrypted or not.
+* `secret`  Sets the secret used for encrypting experiment cookies.
+* `experiments` Defaults to `{}`. It is easiest to load this from a `.yml` file with `YAML.load_file(File.join('config','experiments.yml'))`. The YAML file should have a structure matching the following example:
 
 ```
 :experiment_1:
   :name: Awesome Experiment
   :version: 1
+  :start_at: '2026-08-11T11:55:40Z'
+  :end_at: '2026-08-11T11:55:40Z'
   :variations:
     :a:
       :name: Variation A
@@ -43,11 +45,132 @@ The following configurations are available:
         :message: B is an all-star!
 ```
 
-Usage
+Valid cookie attributes:
+
+* `domain` Sets the domain scope for the eeny-meeny cookies.
+* `expires` Sets the date/time where the cookie gets deleted from the browser. If `end_at` have been specified for the experiment, then the `end_at` time will be used. Otherwise this value will default to `1.month.from_now`.
+* `httponly` Directs browsers not to expose cookies through channels other than HTTP (and HTTPS) requests.
+* `max_age` Can be used to set the cookie's expiration as an interval of seconds in the future, relative to the time the browser received the cookie.
+* `path` Sets the `path` cookie attribute. If this configuration is set to `nil` it means that each page will get its own cookie.
+* `same_site` Accepts: `:strict`, `:lax` and `nil`. Sets the `SameSite` cookie attribute. Selecting `nil` will disable the header on the cookie.
+* `secure` Is meant to keep cookie communication limited to encrypted transmission, directing browsers to use cookies only via secure/encrypted connections.
+
+You can find more information about cookie attributes at: https://en.wikipedia.org/wiki/HTTP_cookie#Cookie_attributes
+
+Example configuration in Rails environment file:
+```
+# load experiments and set secret. Use default cookies configuration.
+config.eeny_meeny = {
+      experiments: YAML.load_file(File.join('config','experiments.yml')),
+      secret: 'my secret'
+  }
+# disable encryption, httponly and set same_site to :lax.
+config.eeny_meeny = {
+      cookies:  { httponly: false, path: '/', same_site: :lax },
+      experiments: YAML.load_file(File.join('config','experiments.yml')),
+      secure: false
+  }
+```
+Example configuration from initializer:
+```
+# load experiments and set secret. Use default cookies configuration.
+EenyMeeny.configure do |config|
+    config.experiments = YAML.load_file(File.join('config','experiments.yml'))
+    config.secret      = 'my secret'
+end
+```
+
+Helpers
 -------------
 `eeny-meeny` adds the following helpers to your controllers and views:
 
-* `participates_in?(experiement_id, variation_id: nil)` Returns the chosen variation for the current user if he participates in the experiment.
+* `participates_in?(experiement_id, variation_id: nil)` Returns the chosen variation for the current user if he participates in the experiment. Otherwise it returns `nil`.
+* `smoke_test?(smoke_test_id, version: 1)` If the current user has a valid cookie for the smoke test that cookie value is returned. Otherwise it returns `nil`.
+
+Route Constraints
+-------------
+`eeny-meeny` allows you to use the following route constraints:
+
+* `EenyMeeny::ExperimentConstraint` allows you to route participants of an experiment and/or experiment variation to a different route than non-participants.
+* `EenyMeeny::SmokeTestConstraint` allows you to route traffic from users with a smoke test cookie to a different route than non-participants.
+
+In order to use the route constraints you need to require them in `routes.rb` (e.g. `require 'eeny-meeny/routing/experiment_constraint'` and `require 'eeny-meeny/routing/smoke_test_constraint'`)
+
+Rake tasks
+-------------
+`eeny-meeny` adds the following rake tasks to your project.
+
+* `eeny_meeny:cookies:experiment[experiment_id]`. Creates and outputs a valid cookie for the given experiment id.
+* `eeny_meeny:cookies:experiment_variation[experiment_id,variation_id]` creates and outputs a valid cookie for the given variation of the experiment with the given experiment_id.
+* `eeny_meeny:cookies:smoke_test[smoke_test_id,version]` Creates and outputs a valid smoke test cookie for a smoke test with the given id and version. `version` will default to `1` if not given.
+
+You can execute the rake tasks like this:
+
+* `rake eeny_meeny:cookies:experimet[experiment_id]`
+* `rake eeny_meeny:cookies:experimet_variation[experiment_id, a]`
+* `rake eeny_meeny:cookies:smoke_test[shadow]`
+* `rake eeny_meeny:cookies:smoke_test[shadow,2]`
+
+You can add the resulting cookie to your browser by copying the cookie string and use the following command in the JS console of your browser.
+
+```
+document.cookie = '<cookie string excluding httponly>';
+```
+
+Please note that the `HttpOnly` attribute will prevent you from adding the cookie to your browser through JS. You will therefor have to remove the `HttpOnly` part of the cookie string before adding the cookie to your browser.
+
+Setting up Experiments
+-------------
+It is easiest to define your experiments in YAML files and load them with as shown in the **Configuration** section.
+
+When setting up a new experiment you need to provide the following information:
+
+* `experiment_id` This is the key that encapsulates the rest of your experiment configuration in the YAML file (see `:experiment_1:` the **Configuration** section).
+* `name` The name/title of your experiment.
+* `version` (optional) the version of your experiment. Defaults to `1`.
+* `start_at` (optional) the start time of your experiment. Will enable the experiment at the given time.
+* `end_at` (optional) the end time of your experiment. Will disable the experiment at the given time.
+* `variations` The set of variations to be included in your experiment (see options for variations below).
+
+A variation needs the following information:
+
+* `variation_id` This is the key that encapsulates the rest of your variation configuration in the YAML file (see `:a:` the **Configuration** section).
+* `name` The name/title of your varition.
+* `weight` The weight of the variation. Defaults to `1`. This can be a floating or integer number. The final weight of the variation will be `weight / sum_of_variation_weights`.
+* `options` (optional) a hash with variation specific information that you want stored want to use in your experiment. Notice that this information will be stored in the experiment cookie so avoid putting sensitive data in there - especially if you choose to disable the cookie encryption.
+
+If you want to force all your users to get their experiment cookie updated, then you can change the `version` option on your experiment. This might for instance be useful if you want to remove an under-performing variation from your experiment. Or when gradually rolling a feature out to the public.
+
+Split testing
+-------------
+The `eeny-meeny` gem can be used to split test features in your Rails application. The goal of split testing is to test a new feature/design/component on your website on a selected fraction of the website sessions and measure its performance.
+
+With `eeny-meeny` you are able to testing multiple variations and select the weight of each experiment variation. This allows you to fine-tune your experiment and gradually roll a change out to your users.
+
+If you want to render a different partial as for users that participates in a specific variation of your experiment, then you can use the `participates_in?(experiment_id, variation_id: variation_id)` helper in your view.
+
+```
+...
+%div.content
+    - if participates_in?(:my_experiment, variation_id: :my_variation)
+        = render 'my_variation_partial'
+    - else
+        = render 'normal_partial'
+```
+
+If you want to do slightly different things in your controller for users that participates in a variation of your experiment, then you can do as follows:
+
+```
+def show
+    if participates_in?(:my_experiment, variation_id: :my_variation)
+        # variation specific code
+    else
+        # normal code
+    end
+end
+```
+
+It is also possible to use `participates_in?(:my_experiment)` to get the variation that the user participates in; and possible show the data stored in the experiment variation.
 
 Full page split tests
 -------------
@@ -68,17 +191,60 @@ If you want to completely redesign a page but test it in production as a split t
 
  2. Namespace your controller and views (ex. `ExamplesController` becommes `V1::ExamplesController` )
  3. Copy the route(s) for `ExamplesController` and use `controller: 'v1/examples`
- 4. Add `require 'eeny-meeny/route_constraint` to `routes.rb`
+ 4. Add `require 'eeny-meeny/routing/experiment_constraint` to `routes.rb`
  4. Surround your `v1/examples` route(s) with the following constraint:
 
     ```
-    constraints(EenyMeeny::RouteConstraint.new(:example_page, variation_id: :v1) do
+    constraints(EenyMeeny::ExperimentConstraint.new(:example_page, variation_id: :v1) do
         # your v1 routes goes here.
     end
     ```
 
 Now 90% of the users will experience V1 and 10% will experience V2.
 
+Measuring your results
+-------------
+`eeny-meeny` leaves the choice of how to measure your results entirely in your hands.
+
+If you track via Google Analytics (GA) or Google Tag Manager (GTM) then add markup / js events to the pages you render and measure the results in the Google Analytics interface.
+
+If you prefer to track results / conversions in a different system then use the `participates_in?` helper to learn the user variation and send an event to your preferred analytics tool from your controller or from JS in the browser.
+
+Smoke testing
+-------------
+The `eeny-meeny` gem can be used to let you test features in production without your users seeing them. It also allows you to keep hidden features in production that only will be available to the selected few that have a valid encrypted smoke test cookie in their browser.
+
+If you want a specific route to only be available as a smoke test, then you can add the following route.
+
+    ```
+    constraints(EenyMeeny::SmokeTestConstraint.new(:shadow_test) do
+        # your 'shadow test' routes
+    end
+    ```
+
+If you want to render a different partial as a smoke test, then you can use the `smoke_test?(smoke_test_id)` helper in your view.
+
+```
+...
+%div.content
+    - if smoke_test?(:shadow_test)
+        = render 'smoke_test_partial'
+    - else
+        = render 'normal_partial'
+```
+
+If you want to do slightly different things in your controller as a smoke test, then you can do as follows:
+
+```
+def show
+    if smoke_test?(:shadow_test)
+        # smoke test specific code
+    else
+        # normal code
+    end
+end
+```
+
 Special thanks
 -------------
 As part of building this gem I borrowed the `Encryptor` class from the `encrypted_cookie` gem (https://github.com/cvonkleist/encrypted_cookie)

data/eeny-meeny.gemspec

@@ -3,8 +3,8 @@ require File.expand_path('../lib/eeny-meeny/version', __FILE__)
 Gem::Specification.new do |s|
   s.name        = 'eeny-meeny'
   s.version     = EenyMeeny::VERSION.dup
-  s.date        = '2016-07-03'
-  s.summary     = "A simple split testing tool for Rails"
+  s.date        = '2016-09-11'
+  s.summary     = "A simple split and smoke testing tool for Rails"
   s.authors     = ["Christian Orthmann"]
   s.email       = 'christian.orthmann@gmail.com'
   s.require_path = 'lib'
@@ -18,6 +18,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency('simplecov', '~> 0')
   s.add_development_dependency('simplecov-rcov', '~> 0')
   s.add_development_dependency('yard', '~> 0')
+  s.add_development_dependency('rack-test', '~> 0.6.3')
   s.add_runtime_dependency('rack', '>= 1.2.1', '< 2')
   s.add_runtime_dependency('activesupport', '>= 3.0.0', '< 5.0.0')
 end

data/lib/eeny-meeny.rb

@@ -1,6 +1,33 @@
 require 'eeny-meeny/version'
 require 'eeny-meeny/railtie' if defined?(Rails)
+require 'eeny-meeny/models/encryptor'
 
 module EenyMeeny
-  EENY_MEENY_COOKIE_PREFIX = 'eeny_meeny_'.freeze
+
+  class Config
+    attr_accessor :cookies, :experiments, :secret, :secure
+
+    attr_reader :encryptor
+
+    def initialize
+      @cookies     = { http_only: true, path: '/', same_site: :strict }
+      @experiments = {}
+      @secret      = '9fc8b966eca7d03d55df40c01c10b8e02bf1f9d12d27b8968d53eb53e8c239902d00bf6afae5e726ce1111159eeb2f8f0e77233405db1d82dd71397f651a0a4f'
+      @secure      = true
+      @encryptor   = (@secure ? EenyMeeny::Encryptor.new(@secret) : nil)
+    end
+  end
+  
+  def self.config
+    @@config ||= Config.new
+  end
+
+  def self.configure
+    yield self.config
+  end
+
+  def self.reset!
+    @@config = nil
+  end
+
 end

data/lib/eeny-meeny/experiment_helper.rb

@@ -1,21 +1,23 @@
-require 'eeny-meeny/shared_methods'
+require 'eeny-meeny/models/cookie'
+require 'eeny-meeny/models/experiment'
 
 module EenyMeeny::ExperimentHelper
-  @@eeny_meeny_encryptor = nil
 
   def participates_in?(experiment_id, variation_id: nil)
-    cookie = eeny_meeny_cookie(experiment_id)
+    experiment = EenyMeeny::Experiment.find_by_id(experiment_id)
+    return unless experiment.active?
+    cookie = read_cookie(EenyMeeny::Cookie.cookie_name(experiment))
     cookie[:variation] unless cookie.nil? || (variation_id.present? && variation_id != cookie[:variation].id)
   end
 
+  def smoke_test?(smoke_test_id, version: 1)
+    cookie = read_cookie(EenyMeeny::Cookie.smoke_test_name(smoke_test_id, version: version))
+    cookie unless cookie.nil?
+  end
+
   private
 
-  def eeny_meeny_cookie(experiment_id)
-    cookie = cookies[EenyMeeny::EENY_MEENY_COOKIE_PREFIX+experiment_id.to_s+'_v'+experiment_version(experiment_id).to_s]
-    if cookie
-      Marshal.load(decrypt(cookie)) rescue nil
-    end
+  def read_cookie(cookie_name)
+    EenyMeeny::Cookie.read(cookies[cookie_name])
   end
-
-  include EenyMeeny::SharedMethods
 end

data/lib/eeny-meeny/middleware.rb

@@ -1,22 +1,17 @@
 require 'rack'
 require 'time'
 require 'active_support/time'
-require 'eeny-meeny/middleware_helper'
-require 'eeny-meeny/experiment'
-require 'eeny-meeny/encryptor'
+require 'eeny-meeny/models/experiment'
+require 'eeny-meeny/models/encryptor'
+require 'eeny-meeny/models/cookie'
 
 module EenyMeeny
   class Middleware
-    include EenyMeeny::MiddlewareHelper
 
-    def initialize(app, experiments, secure, secret, cookie_path, cookie_same_site)
+    def initialize(app)
       @app = app
-      @experiments = experiments.map do |id, experiment|
-        EenyMeeny::Experiment.new(id, **experiment)
-      end
-      @secure = secure
-      @cookie_config = { path: cookie_path, same_site: cookie_same_site }
-      @encryptor = EenyMeeny::Encryptor.new(secret) if secure
+      @experiments = EenyMeeny::Experiment.find_all
+      @cookie_config = EenyMeeny.config.cookies
     end
 
     def call(env)
@@ -27,22 +22,20 @@ module EenyMeeny
       existing_set_cookie_header = env['Set-Cookie']
       # Prepare for experiments.
       @experiments.each do |experiment|
-        # Skip experiments that haven't started yet or if it ended
-        next if experiment.start_at && (now < experiment.start_at)
-        next if experiment.end_at && (now > experiment.end_at)
+        # Skip inactive experiments
+        next unless experiment.active?(now)
         # skip experiments that already have a cookie
-        unless has_experiment_cookie?(cookies, experiment)
+        unless cookies.has_key?(EenyMeeny::Cookie.cookie_name(experiment))
           env['Set-Cookie'] = ''
-          cookie_value = generate_cookie_value(experiment, @cookie_config)
-          cookie_value[:value] = @encryptor.encrypt(cookie_value[:value]) if @secure
+          cookie = EenyMeeny::Cookie.create_for_experiment(experiment, @cookie_config)
           # Set HTTP_COOKIE header to enable experiment on first pageview
           Rack::Utils.set_cookie_header!(env,
-                                         experiment_cookie_name(experiment),
-                                         cookie_value)
+                                         cookie.name,
+                                         cookie.to_h)
           env['HTTP_COOKIE'] = '' if env['HTTP_COOKIE'].nil?
           env['HTTP_COOKIE'] += '; ' unless env['HTTP_COOKIE'].empty?
           env['HTTP_COOKIE'] += env['Set-Cookie']
-          new_cookies[experiment_cookie_name(experiment)] = cookie_value
+          new_cookies[cookie.name] = cookie
         end
       end
       # Clean up 'Set-Cookie' header.
@@ -56,7 +49,7 @@ module EenyMeeny
       response = Rack::Response.new(body, status, headers)
       # Add new cookies to 'Set-Cookie' header
       new_cookies.each do |key, value|
-        response.set_cookie(key,value)
+        response.set_cookie(key,value.to_h)
       end
       response.finish
     end

data/lib/eeny-meeny/models/cookie.rb

@@ -0,0 +1,104 @@
+require 'rack'
+
+module EenyMeeny
+  class Cookie
+    COOKIE_PREFIX = 'eeny_meeny_'.freeze
+    SMOKE_TEST_PREFIX = 'smoke_test_'.freeze
+
+    attr_accessor :value
+    attr_reader :name, :expires, :httponly, :same_site, :path
+
+    def self.create_for_experiment_variation(experiment, variation_id, config = {})
+      variation = experiment.variations.detect { |variation| variation.id == variation_id }
+      raise "Variation '#{variation_id}' not found for Experiment '#{experiment.id}'" if variation.nil?
+      options = {
+          name: cookie_name(experiment),
+          value: Marshal.dump({
+                                  name: experiment.name,
+                                  variation: variation
+                              })
+      }
+      options[:expires] = experiment.end_at if experiment.end_at
+      if EenyMeeny.config.secure
+        options[:value] = EenyMeeny.config.encryptor.encrypt(options[:value])
+      end
+      new(**options.merge(config))
+    end
+
+    def self.create_for_experiment(experiment, config = {})
+      options = {
+          name: cookie_name(experiment),
+          value: Marshal.dump({
+                                  name: experiment.name,
+                                  variation: experiment.pick_variation
+                              })
+      }
+      options[:expires] = experiment.end_at if experiment.end_at
+      if EenyMeeny.config.secure
+        options[:value] = EenyMeeny.config.encryptor.encrypt(options[:value])
+      end
+      new(**options.merge(config))
+    end
+
+    def self.create_for_smoke_test(smoke_test_id, version: 1, **config)
+      options = {
+          name: smoke_test_name(smoke_test_id, version: version),
+          value: Marshal.dump({
+                                  name: smoke_test_id,
+                                  version: version
+                              })
+      }
+      if EenyMeeny.config.secure
+        options[:value] = EenyMeeny.config.encryptor.encrypt(options[:value])
+      end
+      new(**options.merge(config))
+    end
+
+    def self.smoke_test_name(smoke_test_id, version: 1)
+      return if smoke_test_id.nil?
+      SMOKE_TEST_PREFIX+smoke_test_id.to_s+'_v'+version.to_s
+    end
+
+    def self.cookie_name(experiment)
+      return if experiment.nil?
+      COOKIE_PREFIX+experiment.id.to_s+'_v'+experiment.version.to_s
+    end
+
+    def self.read(cookie_string)
+      return if cookie_string.nil? || cookie_string.empty?
+      begin
+        return Marshal.load(cookie_string) unless EenyMeeny.config.secure # Cookie encryption disabled.
+        Marshal.load(EenyMeeny.config.encryptor.decrypt(cookie_string))
+      rescue
+        nil # Return nil if cookie is invalid.
+      end
+    end
+
+    def initialize(name: '', value: '', expires: 1.month.from_now, http_only: true, same_site: nil, path: nil)
+      @name      = name
+      @expires   = expires
+      @httponly  = http_only
+      @value     = value
+      @same_site = same_site
+      @path      = path
+    end
+
+    def to_h
+      hash = {
+          expires: @expires,
+          httponly: @httponly,
+          value: @value
+      }
+      hash[:same_site] = @same_site unless @same_site.nil?
+      hash[:path] = @path unless @path.nil?
+      hash
+    end
+
+    def to_s
+      header = {}
+      Rack::Utils.set_cookie_header!(header, name, to_h)
+      header['Set-Cookie']
+    end
+
+  end
+end