add weighting

Author: alex-stripe

README.md

@@ -66,7 +66,7 @@ Once the user has successfully completed the experiment, say paid and navigated
 
     <script>
       Abba('Checkout')
-        .control()
+        .control('Control')
         .variant('Text: Complete Purchase', function(){
           $('form button').text('Complete Purchase');
         })
@@ -85,6 +85,38 @@ If set the `persist` option to `true`, then the experiment won't be reset once i
     <script>
       Abba('Pricing', {persist: true}).complete();
     </script>
+    
+You can set a variant weight, so some variants are used more than others:
+
+    Abba('My Checkout')
+      .control('Control', {weight: 20})
+      .variant('Variant 1', {weight: 3}, function(){
+        $('#test').text('Variant 1 was chosen!');
+      })
+      .variant('Variant 2', {weight: 3}, function(){
+        $('#test').text('Variant 2 was chosen!');
+      })
+      .start();
+      
+In the case above, the Control will be invoked 20 times more often than the other variants.
+
+You can continue a previously started test using `continue()`.
+
+    Abba('My Checkout')
+      .control()
+      .variant('Variant 1', function(){
+        $('#test').text('Variant 1 was chosen!');
+      })
+      .variant('Variant 2', function(){
+        $('#test').text('Variant 2 was chosen!');
+      })
+      .continue();
+
+Nothing will be recorded if you call `continue()` instead of `start()`. If a variant hasn't been chosen previously, nothing will be executed.
+
+You can reset tests using `reset()`.
+
+    Abba('My Checkout').reset();
 
 ## Credits
 

app/assets/javascripts/client/index.coffee

@@ -70,21 +70,45 @@ class @Abba
 
     @endpoint = @options.endpoint or @constructor.endpoint
 
-  variant: (name, callback) ->
+  variant: (name, options, callback) ->
     if typeof name isnt 'string'
       throw new Error('Variant name required')
 
-    @variants.push(name: name, callback: callback)
+    if typeof options isnt 'object'
+      callback = options
+      options  = {}
+
+    options.name     = name
+    options.callback = callback
+
+    @variants.push(options)
     this
 
-  control: (name = 'Control', callback) =>
-    @variants.push(name: name, callback: callback, control: true)
+  control: (name, options, callback) =>
+    if typeof name isnt 'string'
+      throw new Error('Variant name required')
+
+    if typeof options isnt 'object'
+      callback = options
+      options  = {}
+
+    options.name     = name
+    options.callback = callback
+    options.control  = true
+
+    @variants.push(options)
+    this
+
+  continue: =>
+    # Use the same variant as before, don't record anything
+    if variant = @getPreviousVariant()
+      @useVariant(variant)
     this
 
   start: (name, options = {}) =>
     if variant = @getPreviousVariant()
       # Use the same variant as before, don't record anything
-      @chooseVariant(variant)
+      @useVariant(variant)
       return this
 
     if name?
@@ -95,13 +119,19 @@ class @Abba
         control: options.control
 
     else
-      # Or choose a random one
-      random  = Math.floor(Math.random() * @variants.length)
-      variant = @variants[random]
+      # Or choose a weighted random variant
+      totalWeight   = 0
+      totalWeight  += (v.weight ? 1) for v in @variants
+      randomWeight  = Math.floor(Math.random() * totalWeight)
+      variantWeight = 0
+
+      for variant in @variants
+        variantWeight += variant.weight or 0
+        break if variantWeight >= randomWeight
 
     throw new Error('No variants added') unless variant
     @recordStart(variant)
-    @chooseVariant(variant)
+    @useVariant(variant)
     this
 
   complete: (name) =>
@@ -132,7 +162,7 @@ class @Abba
   getVariantForName: (name) =>
     (v for v in @variants when v.name is name)[0]
 
-  chooseVariant: (variant) =>
+  useVariant: (variant) =>
     variant?.callback?()
     @chosen = variant
 

public/test/start.html

@@ -5,14 +5,31 @@ <h1 id="test">The control was chosen!</h1>
 
 <script type="text/javascript" charset="utf-8">
   Abba('My Checkout')
-    .control()
-    .variant('Variant 1', function(){
+    .control('Control', {weight: 20})
+    .variant('Variant 1', {weight: 3}, function(){
       $('#test').text('Variant 1 was chosen!');
     })
-    .variant('Variant 2', function(){
+    .variant('Variant 2', {weight: 3}, function(){
       $('#test').text('Variant 2 was chosen!');
     })
     .start();
+
+  // Reset test
+  // Abba('My Checkout').reset();
+
+  // Continue a previously started test
+  // Abba('My Checkout')
+  //   .control()
+  //   .variant('Variant 1', function(){
+  //     $('#test').text('Variant 1 was chosen!');
+  //   })
+  //   .variant('Variant 2', function(){
+  //     $('#test').text('Variant 2 was chosen!');
+  //   })
+  //   .continue();
+
+  // Chose a specific variant
+  // Abba('My Checkout').start('Another var');
 </script>
 
 <p>