split 0.2.1 → 0.2.2

data/.gitignore

@@ -2,3 +2,4 @@
 .bundle
 Gemfile.lock
 pkg/*
+*.rbc

data/CHANGELOG.mdown

@@ -1,3 +1,18 @@
+## 0.2.2 (June 11, 2011)
+
+Features:
+
+  - Updated redis-namespace requirement to 1.0.3
+  - Added a configuration object for changing options
+  - Robot regex can now be changed via a configuration options
+  - Added ability to ignore visits from specified IP addresses
+  - Dashboard now shows percentage improvement of alternatives compared to the control
+  - If the alternatives of an experiment are changed it resets the experiment and uses the new alternatives
+
+Bugfixes:
+
+  - Saving an experiment multiple times no longer creates duplicate alternatives
+
 ## 0.2.1 (May 29, 2011)
 
 Bugfixes:

data/README.mdown

@@ -8,6 +8,8 @@ Split is heavily inspired by the Abingo and Vanity rails ab testing plugins and
 
 Split uses redis as a datastore.
 
+Split only supports redis 2.0 or greater.
+
 If you're on OS X, Homebrew is the simplest way to install Redis:
 
     $ brew install redis
@@ -33,6 +35,14 @@ and require it in your project:
 
     require 'split'
 
+### SystemTimer
+
+If you are using Redis on Ruby 1.8.x then you will likely want to also use the SystemTimer gem if you want to make sure the Redis client will not hang.
+
+Put the following in your gemfile as well:
+
+    gem 'SystemTimer'
+
 ### Rails
 
 Split is autoloaded when rails starts up, as long as you've configured redis it will 'just work'.
@@ -114,6 +124,15 @@ You may want to password protect that page, you can do so with `Rack::Auth::Basi
 
 ## Configuration
 
+You can override the default configuration options of Split like so:
+
+    Split.configure do |config|
+      config.robot_regex = /my_custom_robot_regex/
+      config.ignore_ip_addresses << '81.19.48.130'
+    end
+
+### Redis
+
 You may want to change the Redis host and port Split connects to, or
 set various other options at startup.
 
@@ -157,7 +176,7 @@ in your Redis server.
 
 Simply use the `Split.redis.namespace` accessor:
 
-    Split.redis.namespace = "resque:GitHub"
+    Split.redis.namespace = "split:blog"
 
 We recommend sticking this in your initializer somewhere after Redis
 is configured.
@@ -169,7 +188,14 @@ Special thanks to the following people for submitting patches:
 * Lloyd Pick
 * Jeffery Chupp
 
-## Note on Patches/Pull Requests
+## Development
+
+Source hosted at [GitHub](http://github.com/andrew/split).
+Report Issues/Feature requests on [GitHub Issues](http://github.com/andrew/split/issues).
+
+Tests can be ran with `rake spec`
+
+### Note on Patches/Pull Requests
 
  * Fork the project.
  * Make your feature addition or bug fix.

data/lib/split.rb

@@ -3,10 +3,13 @@ require 'split/experiment'
 require 'split/alternative'
 require 'split/helper'
 require 'split/version'
+require 'split/configuration'
 require 'redis/namespace'
 
 module Split
   extend self
+  attr_accessor :configuration
+
   # Accepts:
   #   1. A 'hostname:port' string
   #   2. A 'hostname:port:db' string (to select the Redis db)
@@ -41,8 +44,21 @@ module Split
     self.redis = 'localhost:6379'
     self.redis
   end
+
+  # Call this method to modify defaults in your initializers.
+  #
+  # @example
+  #   Split.configure do |config|
+  #     config.ignore_ips = '192.168.2.1'
+  #   end
+  def configure
+     self.configuration ||= Configuration.new
+     yield(configuration)
+   end
 end
 
+Split.configure {}
+
 if defined?(Rails)
   class ActionController::Base
     ActionController::Base.send :include, Split::Helper

data/lib/split/alternative.rb

@@ -12,6 +12,10 @@ module Split
       @completed_count = counters['completed_count'].to_i
     end
 
+    def to_s
+      name
+    end
+
     def increment_participation
       @participant_count +=1
       self.save
@@ -22,6 +26,10 @@ module Split
       self.save
     end
 
+    def control?
+      experiment.control.name == self.name
+    end
+
     def conversion_rate
       return 0 if participant_count.zero?
       (completed_count.to_f/participant_count.to_f)
@@ -71,6 +79,10 @@ module Split
       save
     end
 
+    def delete
+      Split.redis.del("#{experiment_name}:#{name}")
+    end
+
     def self.find(name, experiment_name)
       counters = Split.redis.hgetall "#{experiment_name}:#{name}"
       self.new(name, experiment_name, counters)

data/lib/split/configuration.rb

@@ -0,0 +1,11 @@
+module Split
+  class Configuration
+    attr_accessor :robot_regex
+    attr_accessor :ignore_ip_addresses
+
+    def initialize()
+      @robot_regex = /\b(Baidu|Gigabot|Googlebot|libwww-perl|lwp-trivial|msnbot|SiteUptime|Slurp|WordPress|ZIBB|ZyBorg)\b/i
+      @ignore_ip_addresses = []
+    end
+  end
+end

data/lib/split/dashboard.rb

@@ -20,7 +20,11 @@ module Split
       end
 
       def number_to_percentage(number, precision = 2)
-        BigDecimal.new((number * 100).to_s).round(precision).to_f
+        round(number * 100)
+      end
+
+      def round(number, precision = 2)
+        BigDecimal.new(number.to_s).round(precision).to_f
       end
     end
 
@@ -33,7 +37,6 @@ module Split
       @experiment = Split::Experiment.find(params[:experiment])
       @alternative = Split::Alternative.find(params[:alternative], params[:experiment])
       @experiment.winner = @alternative.name
-      @experiment.save
       redirect url('/')
     end
 

data/lib/split/dashboard/public/dashboard.js

@@ -5,3 +5,11 @@ function confirmReset() {
   else
     return false;
 }
+
+function confirmWinner() {
+  var agree=confirm("This will now be returned for all users. Are you sure?");
+  if (agree)
+    return true;
+  else
+    return false;
+}

data/lib/split/dashboard/public/style.css

@@ -35,6 +35,7 @@ h2{
 }
 
 .reset{
+  display:inline-block;
   font-size:10px;
   line-height:38px;
 }
@@ -47,4 +48,11 @@ h2{
   clear:both;
 }
 
+.worse, .better{
+  color:#F00;
+  font-size:10px;
+}
 
+.better{
+  color:#00D500;
+}

data/lib/split/dashboard/views/index.erb

@@ -25,8 +25,21 @@
           <td><%= alternative.participant_count %></td>
           <td><%= alternative.participant_count - alternative.completed_count %></td>
           <td><%= alternative.completed_count %></td>
-          <td><%= number_to_percentage(alternative.conversion_rate) %>%</td>
-          <td><%= alternative.z_score %></td>
+          <td>
+            <%= number_to_percentage(alternative.conversion_rate) %>%
+            <% if experiment.control.conversion_rate > 0 && !alternative.control? %>
+              <% if alternative.conversion_rate > experiment.control.conversion_rate %>
+                <span class='better'>
+                  +<%= number_to_percentage((alternative.conversion_rate/experiment.control.conversion_rate)-1) %>%
+                </span>
+              <% elsif alternative.conversion_rate < experiment.control.conversion_rate %>
+                <span class='worse'>
+                  <%= number_to_percentage((alternative.conversion_rate/experiment.control.conversion_rate)-1) %>%
+                </span>
+              <% end  %>
+            <% end %>
+          </td>
+          <td><%= round(alternative.z_score, 3) %></td>
           <td>
             <% if experiment.winner %>
               <% if experiment.winner.name == alternative.name %>
@@ -35,7 +48,7 @@
                 Loser
               <% end %>
             <% else %>
-              <form action="<%= url experiment.name %>" method='post'>
+              <form action="<%= url experiment.name %>" method='post' onclick="return confirmWinner()">
                 <input type='hidden' name='alternative' value='<%= alternative.name %>'>
                 <input type="submit" value="Use this">
               </form>

data/lib/split/experiment.rb

@@ -38,15 +38,19 @@ module Split
     end
 
     def reset
-      alternatives.each do |alternative|
-        alternative.reset
-      end
+      alternatives.each(&:reset)
       reset_winner
     end
 
+    def new_record?
+      !Split.redis.exists(name)
+    end
+
     def save
-      Split.redis.sadd(:experiments, name)
-      @alternative_names.reverse.each {|a| Split.redis.lpush(name, a) }
+      if new_record?
+        Split.redis.sadd(:experiments, name)
+        @alternative_names.reverse.each {|a| Split.redis.lpush(name, a) }
+      end
     end
 
     def self.load_alternatives_for(name)
@@ -75,12 +79,20 @@ module Split
 
     def self.find_or_create(name, *alternatives)
       if Split.redis.exists(name)
-        return self.new(name, *load_alternatives_for(name))
+        if load_alternatives_for(name) == alternatives
+          experiment = self.new(name, *load_alternatives_for(name))
+        else
+          exp = self.new(name, *load_alternatives_for(name))
+          exp.reset
+          exp.alternatives.each(&:delete)
+          experiment = self.new(name, *alternatives)
+          experiment.save
+        end
       else
         experiment = self.new(name, *alternatives)
         experiment.save
-        return experiment
       end
+      return experiment
     end
   end
 end

data/lib/split/helper.rb

@@ -8,7 +8,7 @@ module Split
         return forced_alternative
       end
 
-      ab_user[experiment_name] = experiment.control.name if is_robot?
+      ab_user[experiment_name] = experiment.control.name if exclude_visitor?
 
       if ab_user[experiment_name]
         return ab_user[experiment_name]
@@ -21,7 +21,7 @@ module Split
     end
 
     def finished(experiment_name)
-      return if is_robot?
+      return if exclude_visitor?
       alternative_name = ab_user[experiment_name]
       alternative = Split::Alternative.find(alternative_name, experiment_name)
       alternative.increment_completion
@@ -36,8 +36,20 @@ module Split
       session[:split] ||= {}
     end
 
+    def exclude_visitor?
+      is_robot? or is_ignored_ip_address?
+    end
+
     def is_robot?
-      request.user_agent =~ /\b(Baidu|Gigabot|Googlebot|libwww-perl|lwp-trivial|msnbot|SiteUptime|Slurp|WordPress|ZIBB|ZyBorg)\b/i
+      request.user_agent =~ Split.configuration.robot_regex
+    end
+
+    def is_ignored_ip_address?
+      if Split.configuration.ignore_ip_addresses.any?
+        Split.configuration.ignore_ip_addresses.include?(request.ip)
+      else
+        false
+      end
     end
   end
 end

data/lib/split/version.rb

@@ -1,3 +1,3 @@
 module Split
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/spec/alternative_spec.rb

@@ -50,7 +50,7 @@ describe Split::Alternative do
     alternative.increment_completion
     alternative.completed_count.should eql(old_completed_count+1)
   end
-  
+
   it "can be reset" do
     alternative = Split::Alternative.new('Basket', 'basket_text', {'participant_count' => 10, 'completed_count' =>4})
     alternative.save
@@ -59,6 +59,15 @@ describe Split::Alternative do
     alternative.completed_count.should eql(0)
   end
 
+  it "should know if it is the control of an experiment" do
+    experiment = Split::Experiment.new('basket_text', 'Basket', "Cart")
+    experiment.save
+    alternative = Split::Alternative.find('Basket', 'basket_text')
+    alternative.control?.should be_true
+    alternative = Split::Alternative.find('Cart', 'basket_text')
+    alternative.control?.should be_false
+  end
+
   describe 'conversion rate' do
     it "should be 0 if there are no conversions" do
       alternative = Split::Alternative.new('Basket', 'basket_text')
@@ -84,7 +93,7 @@ describe Split::Alternative do
       alternative = Split::Alternative.find('red', 'link_color')
       alternative.z_score.should eql(0)
     end
-    
+
     it "should be N/A for the control" do
       experiment = Split::Experiment.find_or_create('link_color', 'blue', 'red')
 

data/spec/configuration_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+
+describe Split::Configuration do
+  it "should provide default values" do
+    config = Split::Configuration.new
+
+    config.ignore_ip_addresses.should eql([])
+    config.robot_regex.should eql(/\b(Baidu|Gigabot|Googlebot|libwww-perl|lwp-trivial|msnbot|SiteUptime|Slurp|WordPress|ZIBB|ZyBorg)\b/i)
+  end
+end

data/spec/dashboard_spec.rb

@@ -0,0 +1,48 @@
+require 'spec_helper'
+require 'rack/test'
+require 'split/dashboard'
+
+describe Split::Dashboard do
+  include Rack::Test::Methods
+
+  def app
+    @app ||= Split::Dashboard
+  end
+
+  it "should respond to /" do
+    get '/'
+    last_response.should be_ok
+  end
+
+  it "should reset an experiment" do
+    experiment = Split::Experiment.find_or_create('link_color', 'blue', 'red')
+    red = Split::Alternative.find('red', 'link_color').participant_count
+
+    red = Split::Alternative.find('red', 'link_color')
+    blue = Split::Alternative.find('blue', 'link_color')
+    red.participant_count = 5
+    red.save
+    blue.participant_count = 6
+    blue.save
+
+    post '/reset/link_color'
+
+    last_response.should be_redirect
+
+    new_red_count = Split::Alternative.find('red', 'link_color').participant_count
+    new_blue_count = Split::Alternative.find('blue', 'link_color').participant_count
+
+    new_blue_count.should eql(0)
+    new_red_count.should eql(0)
+  end
+
+  it "should mark an alternative as the winner" do
+    experiment = Split::Experiment.find_or_create('link_color', 'blue', 'red')
+    experiment.winner.should be_nil
+
+    post '/link_color', :alternative => 'red'
+
+    last_response.should be_redirect
+    experiment.winner.name.should eql('red')
+  end
+end

data/spec/experiment_spec.rb

@@ -8,18 +8,39 @@ describe Split::Experiment do
     experiment = Split::Experiment.new('basket_text', 'Basket', "Cart")
     experiment.name.should eql('basket_text')
   end
-  
+
   it "should have alternatives" do
     experiment = Split::Experiment.new('basket_text', 'Basket', "Cart")
     experiment.alternatives.length.should be 2
   end
-  
+
   it "should save to redis" do
     experiment = Split::Experiment.new('basket_text', 'Basket', "Cart")
     experiment.save
     Split.redis.exists('basket_text').should be true
   end
-  
+
+  it "should not create duplicates when saving multiple times" do
+    experiment = Split::Experiment.new('basket_text', 'Basket', "Cart")
+    experiment.save
+    experiment.save
+    Split.redis.exists('basket_text').should be true
+    Split.redis.lrange('basket_text', 0, -1).should eql(['Basket', "Cart"])
+  end
+
+  describe 'new record?' do
+    it "should know if it hasn't been saved yet" do
+      experiment = Split::Experiment.new('basket_text', 'Basket', "Cart")
+      experiment.new_record?.should be_true
+    end
+
+    it "should know if it has been saved yet" do
+      experiment = Split::Experiment.new('basket_text', 'Basket', "Cart")
+      experiment.save
+      experiment.new_record?.should be_false
+    end
+  end
+
   it "should return an existing experiment" do
     experiment = Split::Experiment.new('basket_text', 'Basket', "Cart")
     experiment.save
@@ -101,5 +122,17 @@ describe Split::Experiment do
       experiment.next_alternative.name.should eql('green')
     end
   end
-end
 
+  describe 'changing an existing experiment' do
+    it "should reset an experiment if it is loaded with different alternatives" do
+      experiment = Split::Experiment.find_or_create('link_color', 'blue', 'red', 'green')
+      blue = Split::Alternative.find('blue', 'link_color')
+      blue.participant_count = 5
+      blue.save
+      same_experiment = Split::Experiment.find_or_create('link_color', 'blue', 'yellow', 'orange')
+      same_experiment.alternatives.map(&:name).should eql(['blue', 'yellow', 'orange'])
+      new_blue = Split::Alternative.find('blue', 'link_color')
+      new_blue.participant_count.should eql(0)
+    end
+  end
+end

data/spec/helper_spec.rb

@@ -1,5 +1,7 @@
 require 'spec_helper'
 
+# TODO change some of these tests to use Rack::Test
+
 describe Split::Helper do
   include Split::Helper
 
@@ -97,6 +99,50 @@ describe Split::Helper do
       @request = OpenStruct.new(:user_agent => 'Googlebot/2.1 (+http://www.google.com/bot.html)')
     end
 
+    describe 'ab_test' do
+      it 'should return the control' do
+        experiment = Split::Experiment.find_or_create('link_color', 'blue', 'red')
+        alternative = ab_test('link_color', 'blue', 'red')
+        alternative.should eql experiment.control.name
+      end
+
+      it "should not increment the participation count" do
+        experiment = Split::Experiment.find_or_create('link_color', 'blue', 'red')
+
+        previous_red_count = Split::Alternative.find('red', 'link_color').participant_count
+        previous_blue_count = Split::Alternative.find('blue', 'link_color').participant_count
+
+        ab_test('link_color', 'blue', 'red')
+
+        new_red_count = Split::Alternative.find('red', 'link_color').participant_count
+        new_blue_count = Split::Alternative.find('blue', 'link_color').participant_count
+
+        (new_red_count + new_blue_count).should eql(previous_red_count + previous_blue_count)
+      end
+    end
+    describe 'finished' do
+      it "should not increment the completed count" do
+        experiment = Split::Experiment.find_or_create('link_color', 'blue', 'red')
+        alternative_name = ab_test('link_color', 'blue', 'red')
+
+        previous_completion_count = Split::Alternative.find(alternative_name, 'link_color').completed_count
+
+        finished('link_color')
+
+        new_completion_count = Split::Alternative.find(alternative_name, 'link_color').completed_count
+
+        new_completion_count.should eql(previous_completion_count)
+      end
+    end
+  end
+  describe 'when ip address is ignored' do
+    before(:each) do
+      @request = OpenStruct.new(:ip => '81.19.48.130')
+      Split.configure do |c|
+        c.ignore_ip_addresses << '81.19.48.130'
+      end
+    end
+
     describe 'ab_test' do
       it 'should return the control' do
         experiment = Split::Experiment.find_or_create('link_color', 'blue', 'red')

data/spec/spec_helper.rb

@@ -14,5 +14,6 @@ end
 def request(ua = 'Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_6; de-de) AppleWebKit/533.20.25 (KHTML, like Gecko) Version/5.0.4 Safari/533.20.27')
   r = OpenStruct.new
   r.user_agent = ua
+  r.ip = '192.168.1.1'
   @request ||= r
 end

data/split.gemspec

@@ -19,9 +19,10 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_dependency(%q<redis>, ["~>  2.1"])
-  s.add_dependency(%q<redis-namespace>, ["~>  0.10.0"])
+  s.add_dependency(%q<redis-namespace>, ["~>  1.0.3"])
   s.add_dependency(%q<sinatra>, ["~>  1.2.6"])
 
   # Development Dependencies
   s.add_development_dependency(%q<rspec>, ["~>  2.6"])
+  s.add_development_dependency(%q<rack-test>, ["~> 0.6"])
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: split
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
   - 2
-  - 1
-  version: 0.2.1
+  - 2
+  version: 0.2.2
 platform: ruby
 authors: 
 - Andrew Nesbitt
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-29 00:00:00 +01:00
+date: 2011-06-12 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -41,12 +41,12 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 55
+        hash: 17
         segments: 
+        - 1
         - 0
-        - 10
-        - 0
-        version: 0.10.0
+        - 3
+        version: 1.0.3
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
@@ -80,6 +80,21 @@ dependencies:
         version: "2.6"
   type: :development
   version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rack-test
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 0
+        - 6
+        version: "0.6"
+  type: :development
+  version_requirements: *id005
 description: 
 email: 
 - andrewnez@gmail.com
@@ -98,6 +113,7 @@ files:
 - Rakefile
 - lib/split.rb
 - lib/split/alternative.rb
+- lib/split/configuration.rb
 - lib/split/dashboard.rb
 - lib/split/dashboard/public/dashboard.js
 - lib/split/dashboard/public/reset.css
@@ -108,6 +124,8 @@ files:
 - lib/split/helper.rb
 - lib/split/version.rb
 - spec/alternative_spec.rb
+- spec/configuration_spec.rb
+- spec/dashboard_spec.rb
 - spec/experiment_spec.rb
 - spec/helper_spec.rb
 - spec/spec_helper.rb
@@ -148,6 +166,8 @@ specification_version: 3
 summary: Rack based split testing framework
 test_files: 
 - spec/alternative_spec.rb
+- spec/configuration_spec.rb
+- spec/dashboard_spec.rb
 - spec/experiment_spec.rb
 - spec/helper_spec.rb
 - spec/spec_helper.rb