easy_ab 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bb6587e7ae47d2f3743e6dc6e6c053e40f993ac2
+  data.tar.gz: f74132d722d8dbb9f7dc275748770ecef6e406b1
+SHA512:
+  metadata.gz: 7c88e4fd12e3c20de12c8a00cae041ca279080501b0f57869b345f651b7b83cb695d21d02ad6b940ed5f9501993afa92e3eb52eb8dafd2fc52718ddb1ff45456
+  data.tar.gz: 2e0014482e2275c87bcabeb39cbc90f78012d6338ddf2075e4c22de991c90a7554580c7d4a8f052cc65457724355606c8951c88d7c717c693307cfda92a6184a

data/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true

data/.gitignore

@@ -0,0 +1,2 @@
+*.gem
+TODO.md

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Chien-Wei Chu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# Easy AB
+
+Easy, flexible A/B testing tool for Rails.
+
+* Design for web
+* Use your database to keep users' testing info to seamlessly handle the transition from guest to signed in user. You don't need to prepare extra stack like Redis or something else.
+* Grouping your users to your predefined variants with very easy and flexible way:
+  * Random with equal weightings.
+  * Random with predefined weightings.
+  * Define Proc(s) to setup your rules. Something like "sign up for 1 month to variant A, others to variant B", "user with odd id to variant A, with even id to variant B", ...
+  Example of using proc to define rules:
+
+  ```ruby
+  # Example 1
+  variants: ['variant A', 'variant B']
+  rules: [
+    -> { current_user.created_at <= 1.month.ago },
+    -> { current_user.created_at > 1.month.ago },
+  ]
+
+  # Example 2
+  variants: ['variant A', 'variant B']
+  rules: [
+    -> { current_user.id.odd? },
+    -> { current_user.id.even? },
+  ]
+  ```
+  and you can change your rules at any time without affecting existing users, they always see the same variant
+* Convenient APIs to
+  * check your view for different variants
+  * output all experiments and the corresponding variants for your users. It's very useful when sending data to analytics services like Google Anayltics, Mixpanel, Kissmetrics, ...
+* No DSL, just setup your rules with pure Ruby (and Rails) :)
+
+# Notice
+Easy AB is under development. Currently don't use in your production app.
+
+# Why Easy AB?
+## Comparisons
+### Split
+### Field Test
+### Flipper
+### ...
+
+# Installation
+
+* Add `gem 'easy_ab'` to your application's Gemfile and run `bundle install`.
+* Run `bin/rails g easy_ab:install`. Migration file and initializer will copy to your app folder.
+* Run `bin/rake db:migrate`
+
+# Setup
+
+Edit `config/initializers/easy_ab.rb` to setup basic configurations.
+
+```ruby
+EasyAb.configure do |config|
+  # Tell the gem how to check whether current user is signed in or not
+  config.user_signed_in_method = -> { user_signed_in? }
+
+  # Tell the gem how to get current user's id
+  config.current_user_id = -> { current_user.id }
+
+  # Tell the gem how to check whether current user is admin or not
+  # Only admin can switch variant by url parameters
+  config.authorize_admin_with = -> { current_user.admin? }
+end
+```
+
+# Getting Started
+
+Setup your experiments in `config/initializers/easy_ab.rb`
+
+Say, if you have an experiment named 'button color', with three equal weighted variants: red, blue, green.
+
+Define your experiment as follows:
+
+``` ruby
+EasyAb.experiments do |experiment|
+  experiment.define :title_color, variants: ['red', 'blue', 'green']
+end
+```
+
+Then you will be able to use the following helpers in controller or view:
+
+```ruby
+color = ab_test(:title_color)
+```
+
+or pass a block
+
+```erb
+<% ab_test(:title_color) do |color| %>
+  <h1 class="<%= color %>">Welcome!</h1>
+<% end %>
+```
+
+For admin, specify a variant with url parameters makes debugging super easy:
+
+```
+?ab_test[title_color]=blue
+```

data/app/models/easy_ab/grouping.rb

@@ -0,0 +1,20 @@
+module EasyAb
+  class Grouping < ActiveRecord::Base
+    self.table_name = 'easy_ab_groupings'
+
+    validates :experiment, presence: true
+    validates :variant, presence: true
+    validates :user_id, uniqueness: { scope: [:experiment] }
+    validates :cookie,  uniqueness: { scope: [:experiment] }
+    validate :user_should_be_present
+
+    private
+
+      def user_should_be_present
+        if cookie.nil? && user_id.nil?
+          errors.add(:user_id, "or cookie can't be blank")
+          errors.add(:cookie, "or user_id can't be blank")
+        end
+      end
+  end
+end

data/easy_ab.gemspec

@@ -0,0 +1,16 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'easy_ab/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'easy_ab'
+  s.version     = EasyAb::VERSION
+  s.summary     = 'Flexible A/B testing and feature toggle for Rails'
+  s.authors     = ['Gary Chu']
+  s.email       = 'icarus4.chu@gmail.com'
+  s.files       = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  s.homepage    = 'https://github.com/icarus4/easy_ab'
+  s.license       = 'MIT'
+end

data/lib/easy_ab/engine.rb

@@ -0,0 +1,8 @@
+module EasyAb
+  class Engine < ::Rails::Engine
+    isolate_namespace EasyAb
+
+    # prevents conflict with field_test method in views
+    engine_name "easy_ab_engine"
+  end
+end

data/lib/easy_ab/experiment.rb

@@ -0,0 +1,112 @@
+module EasyAb
+  class Experiment
+    attr_reader :name, :variants, :weights, :rules
+
+    def initialize(name, options = {})
+      @name = name.to_s
+      @variants = options[:variants]
+      @weights = options[:weights]
+      @rules = options[:rules]
+
+      raise ArgumentError, 'Please define variants' if @variants.blank?
+      raise ArgumentError, 'Number of variants and weights should be identical' if @weights.present? && @weights.size != @variants.size
+      raise ArgumentError, 'Number of variants and rules should be identical' if @rules.present? && @rules.size != @variants.size
+      raise ArgumentError, 'All rules should be a Proc' if @rules.present? && @rules.any? { |rule| !rule.is_a?(Proc) }
+    end
+
+    def self.find_by_name!(experiment_name)
+      experiment_name = experiment_name.to_s
+      exp = EasyAb.experiments.all.find { |exp| exp.name == experiment_name }
+      raise ExperimentNotFound if exp.nil?
+      exp
+    end
+
+    def assign_variant(user_recognition, options = {})
+      grouping = find_grouping_by_user_recognition(user_recognition) || ::EasyAb::Grouping.new(experiment: name, user_id: user_recognition[:id], cookie: user_recognition[:cookie])
+
+      if options[:variant] && variants.include?(options[:variant])
+        grouping.variant = options[:variant]
+      else
+        grouping.variant ||= flexible_variant(options[:contexted_rules])
+      end
+
+      if grouping.changed? && !options[:skip_save]
+        begin
+          grouping.save!
+        rescue ActiveRecord::RecordNotUnique
+          grouping = find_grouping_by_user_recognition(user_recognition)
+        rescue ActiveRecord::RecordInvalid => e
+          if grouping.errors[:user_id].present? || grouping.errors[:cookie].present?
+            grouping = find_grouping_by_user_recognition(user_recognition)
+          else
+            raise e
+          end
+        end
+      end
+
+      grouping.variant
+    end
+
+    def find_grouping_by_user_recognition(user_recognition)
+      user_id = user_recognition[:id]
+      cookie  = user_recognition[:cookie]
+      grouping = nil
+
+      raise 'should assign a cookie' unless cookie
+
+      if user_id # If user login
+        # Case I: User participated experiment with login and return again
+        # Case II: user participated experiment with login and return by another device with login
+        # Case III: user participated experiment with login and return by the same device, but cookie was cleared between last and this participation
+        # => Both II and III already exist a record with the same user_id but different cookie
+        # In the above two cases, we update the cookie of the exising record
+        return grouping if (grouping = groupings.where(user_id: user_id).first) && ((cookie && grouping.cookie = cookie) || true)
+
+        # User participated experiment without login, but this time with login => assign user_id to the existing record
+        return grouping if (grouping = groupings.where(user_id: nil, cookie: cookie).first) && grouping.user_id = user_id
+      else # If user not login
+        return grouping if grouping = groupings.where(cookie: cookie).first
+      end
+
+      # User have yet to participate experiment
+      nil
+    end
+
+    def groupings
+      ::EasyAb::Grouping.where(experiment: name)
+    end
+
+    def flexible_variant(contexted_rules = nil)
+      if contexted_rules
+        variant_by_rule(contexted_rules)
+      elsif weights
+        weighted_variant
+      else
+        equal_weighted_variant
+      end
+    end
+
+    def variant_by_rule(contexted_rules)
+      contexted_rules.each_with_index do |rule, i|
+        return variants[i] if rule.call
+      end
+      # If all rules not matched, apply the first variatn
+      variants.first
+    end
+
+    def weighted_variant
+      total = weights.sum
+      roll = rand
+      sum = 0
+      weights.each_with_index do |weight, i|
+        sum += weight.to_d / total
+        return variants[i] if sum >= roll
+      end
+      variants.last
+    end
+
+    def equal_weighted_variant
+      variants.sample
+    end
+  end
+end

data/lib/easy_ab/helpers.rb

@@ -0,0 +1,102 @@
+module EasyAb
+  module Helpers
+    # Return variant of specified experiment for current user
+    def ab_test(experiment_name, options = {})
+      experiment_name = experiment_name.to_s
+      user_recognition = find_ab_test_user_recognition(options)
+
+      if respond_to?(:request) && params[:ab_test] && params[:ab_test][experiment_name]
+        # Check current user is admin or not by proc defined by gem user
+        if current_user_is_admin?
+          options[:variant] ||= params[:ab_test][experiment_name]
+        end
+        # TODO: exclude bot
+      end
+
+      experiment = EasyAb::Experiment.find_by_name!(experiment_name)
+
+      if experiment.rules.present?
+        @rules_with_current_context ||= experiment.rules.map { |rule| Proc.new { instance_exec(&rule)} }
+        options[:contexted_rules] = @rules_with_current_context
+      end
+
+      @variant_cache ||= {}
+      @variant_cache[experiment_name] ||= experiment.assign_variant(user_recognition, options)
+      block_given? ? yield(@variant_cache[experiment_name]) : @variant_cache[experiment_name]
+    end
+
+    # Return all participated experiments and the corresponding variants for current user
+    # Return format:
+    # {
+    #   'experiment 1' => 'variant 1',
+    #   'experiment 2' => 'variant 2',
+    #   ...
+    # }
+    def participated_experiments(options = {})
+      user_recognition = find_ab_test_user_recognition(options)
+      groupings = if user_recognition[:id]
+                    EasyAb::Grouping.where("user_id = ? OR cookie = ?", user_recognition[:id], user_recognition[:cookie])
+                  else
+                    EasyAb::Grouping.where(cookie: user_recognition[:cookie])
+                  end
+
+      experiments = {}
+      groupings.each do |grouping|
+        experiments[grouping.experiment] = grouping.variant
+      end
+      experiments
+    end
+
+    private
+
+      def find_ab_test_user_recognition(options = {})
+        user_recognition = {}
+
+        # TODO:
+        # return (raise NotImplementedError) if options[:user] && (users << options[:user])
+
+        user_recognition[:id] = current_user_id if current_user_signed_in?
+        # Controllers and views
+        user_recognition[:cookie] = find_or_create_easy_ab_cookie if respond_to?(:request)
+
+        user_recognition
+      end
+
+      def current_user_signed_in?
+        user_signed_in_method_proc.call
+      end
+
+      def current_user_id
+        current_user_id_proc.call
+      end
+
+      def current_user_is_admin?
+        authorize_admin_with_proc.call
+      end
+
+      def authorize_admin_with_proc
+        @authorize_admin_with_proc ||= Proc.new { instance_exec &EasyAb.config.authorize_admin_with }
+      end
+
+      def current_user_id_proc
+        @current_user_id_proc ||= Proc.new { instance_exec &EasyAb.config.current_user_id }
+      end
+
+      def user_signed_in_method_proc
+        @user_signed_in_method_proc ||= Proc.new { instance_exec &EasyAb.config.user_signed_in_method }
+      end
+
+      def find_or_create_easy_ab_cookie
+        cookie_key = :easy_ab
+        value = cookies[cookie_key]
+        value = if value
+                  value.gsub(/[^a-z0-9\-]/i, "")
+                else
+                  SecureRandom.uuid
+                end
+        cookies[cookie_key] = { value: value, expires: 30.days.from_now }
+
+        value
+      end
+  end
+end

data/lib/easy_ab/participant.rb

@@ -0,0 +1,7 @@
+module EasyAb
+  class Participant
+    def self.normalize(participants)
+      participants.map { |p| p.respond_to?(:model_name) ? "#{v.model_name.name}:#{v.id}" : v.to_s }
+    end
+  end
+end

data/lib/easy_ab/version.rb

@@ -0,0 +1,3 @@
+module EasyAb
+  VERSION = '0.0.1'
+end

data/lib/easy_ab.rb

@@ -0,0 +1,56 @@
+require 'easy_ab/experiment'
+require 'easy_ab/engine' if defined?(Rails)
+require 'easy_ab/helpers'
+require 'easy_ab/version'
+
+module EasyAb
+  class Error < StandardError; end
+  class ExperimentNotFound < Error; end
+
+  class << self
+    def config
+      @@config
+    end
+
+    def configure
+      @@config ||= Config.new
+      yield(@@config)
+    end
+
+    def experiments
+      @@experiments ||= Experiments.new
+
+      if block_given?
+        yield(@@experiments)
+      else
+        @@experiments
+      end
+    end
+  end
+
+  class Config
+    attr_accessor :authorize_admin_with, :user_signed_in_method, :current_user_id
+  end
+
+  class Experiments
+    def initialize
+      @experiments = []
+    end
+
+    def define(name, options = {})
+      @experiments << ::EasyAb::Experiment.new(name, options)
+    end
+
+    def all
+      @experiments
+    end
+  end
+end
+
+ActiveSupport.on_load(:action_controller) do
+  include ::EasyAb::Helpers
+end
+
+ActiveSupport.on_load(:action_view) do
+  include ::EasyAb::Helpers
+end

data/lib/generators/easy_ab/install_generator.rb

@@ -0,0 +1,36 @@
+module EasyAb
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path("../templates", __FILE__)
+
+      # Implement the required interface for Rails::Generators::Migration.
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        if ::ActiveRecord::Base.timestamped_migrations
+          [Time.now.utc.strftime("%Y%m%d%H%M%S"), "%.14d" % next_migration_number].max
+        else
+          "%.3d" % next_migration_number
+        end
+      end
+
+      def migration_version
+        if ActiveRecord::VERSION::MAJOR >= 5
+          "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+        end
+      end
+
+      def copy_migration
+        migration_template 'grouping.rb', 'db/migrate/create_easy_ab_groupings.rb', migration_version: migration_version
+      end
+
+      # def copy_config
+      #   template 'easy_ab.yml', 'config/easy_ab.yml'
+      # end
+
+      def copy_initializer_file
+        copy_file 'easy_ab.rb', 'config/initializers/easy_ab.rb'
+      end
+    end
+  end
+end

data/lib/generators/easy_ab/templates/easy_ab.rb

@@ -0,0 +1,26 @@
+EasyAb.configure do |config|
+  # Define how to check whether current user is signed in or not
+  config.user_signed_in_method = -> { user_signed_in? }
+
+  # Define how to get current user's id
+  config.current_user_id = -> { current_user.id }
+
+  # Define how to check whether current user is admin or not
+  # Only admin can switch variant by url parameters
+  config.authorize_admin_with = -> { current_user.admin? }
+end
+
+EasyAb.experiments do |experiment|
+  experiment.define :button_color,
+                    variants: ['red', 'blue', 'yellow'],
+                    weights:  [10, 3, 1]
+
+  experiment.define :title,
+                    variants: ['hello', 'welcome', 'yo'],
+                    rules: [
+                      -> { (1..100).cover?(current_user.id) },
+                      -> { current_user.id.odd? },
+                      -> { current_user.id.even? },
+                    ]
+
+end

data/lib/generators/easy_ab/templates/easy_ab.yml

@@ -0,0 +1,8 @@
+experiments:
+  button_color:
+    variants:
+      - red
+      - green
+      - blue
+    # winner: green
+

data/lib/generators/easy_ab/templates/grouping.rb

@@ -0,0 +1,15 @@
+class <%= migration_class_name %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :easy_ab_groupings do |t|
+      t.integer :user_id
+      t.string :cookie
+      t.string :experiment
+      t.string :variant
+      t.timestamps
+    end
+
+    add_index :easy_ab_groupings, [:experiment, :user_id], unique: true
+    add_index :easy_ab_groupings, :user_id
+    add_index :easy_ab_groupings, :cookie
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: easy_ab
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Gary Chu
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-08-07 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: icarus4.chu@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".gitignore"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- app/models/easy_ab/grouping.rb
+- easy_ab.gemspec
+- lib/easy_ab.rb
+- lib/easy_ab/engine.rb
+- lib/easy_ab/experiment.rb
+- lib/easy_ab/helpers.rb
+- lib/easy_ab/participant.rb
+- lib/easy_ab/version.rb
+- lib/generators/easy_ab/install_generator.rb
+- lib/generators/easy_ab/templates/easy_ab.rb
+- lib/generators/easy_ab/templates/easy_ab.yml
+- lib/generators/easy_ab/templates/grouping.rb
+homepage: https://github.com/icarus4/easy_ab
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: Flexible A/B testing and feature toggle for Rails
+test_files: []
+has_rdoc: