rails_ab_test 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f5167403875fceb6094ff438c561989185882017
-  data.tar.gz: 9e50e9553b8a40c977e2ddf93b5033cf4a31668b
+  metadata.gz: 1eab8c6bad3e294a01e3450bfd378a172caa48ae
+  data.tar.gz: 8c76e60529064f64209412bc1695b2329c539bdc
 SHA512:
-  metadata.gz: 1b1f3d80a3011fa5da019f7cf3dc315f894951d685480b48bb0ec45b58ad2f26f3068165f269939f6863f38d45eb403f19d4a647ecd61fd7f3c6d7aaa6c56bdf
-  data.tar.gz: 886922919aeaa4644d3bfcf75c6194d497329217b118736ab871131e0a5b78d78103f449a86e1fbd8da033f31f8ee146c007291fe034f1158a6c378a65afdc25
+  metadata.gz: 91988263e562a86f21e290cb4e3424ae7508ffd5ffceabeb1c14f7d7b0fd82d9226b40f44f504a478f16fb84e63e60a923f0a1badd59eeb0434fe0d43a57d191
+  data.tar.gz: 0d46ed3f864cbdacf2b187c9f59910a44b7c1f8e3d83008d086b7416390b3355bd1d242a07143e78b7de7b875daa4977019073978e4aea0983f629bda4961334

data/README.md

@@ -1,8 +1,11 @@
 # RailsAbTest
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/rails_ab_test`. To experiment with that code, run `bin/console` for an interactive prompt.
+Perform A/B Testing in your Rails app with ease.
 
-TODO: Delete this and the text above, and describe your gem
+The idea is a combination of
+
+- minimal Code to support A/B Test versioning, is provided by this gem.
+- A simple Pattern to organize the code in views into separated versions for each A/B Test version.
 
 ## Installation
 
@@ -22,20 +25,162 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Let's start with the simplest usage case:
+
+### The Code
+
+Configure your controllers by including the module, normally `ApplicationController` is a good candidate for this:
+
+```ruby
+include RailsAbTest::Controller
+```
+
+Then for the action (`index` in the example) that will be A/B Tested set a `before_filter`:
+
+```ruby
+# a controller
+before_filter :choose_ab_test, only: :index
+```
+
+The method `choose_ab_test` will randomly (with 50% probability) choose A or B as the A/B Test version.
+From here the version chosen will be accessible in your views and helpers in the variable `@ab_test`.
+
+Then inside the action you need to replace `render` with `render_ab`
+
+```ruby
+# a controller
+def index
+  render_ab
+end
+```
+
+`render_ab` will infer the template to render from the action name, and prepend it with `@ab_test` to fully
+determine the template name. i.e. if the A/B Version is A it will render the template `index_A`.
+
+### The Pattern
 
-## Development
+Now you need to make 2 copies of your `index` view template, and name it `index_A` for the A/B Test version A, and
+`index_B` for B.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Make sure you set up different tracking for each version and you are good to go. Your controller's `index` action is ready to be A/B Tested.
+
+## QA and Test support
+
+For testing and QA purposes the A/B Test version can be selected by appending `?ab_test=A` to the url of the page,
+that will make sure the version A is selected.
+
+## More complex usage
+
+### More versions that just A and B
+
+Then instead of a `before_filter` you can call the method `choose_ab_test` directly:
+
+```ruby
+# a controller
+def show
+  choose_ab_test ['A', 'B', 'C'] # this action calls the method directly instead
+  render_ab
+end
+```
+
+Again the 3 versions will have the same probability of being chosen.
+
+*NOTE:* in the current version the gem only supports versions with equal probabilities each.
+
+### 2 actions 1 template
+
+Imagine that the actions `index` and `archive` are both A/B versioned and they share the same template. The action `index` will not change, but `archive` needs to explicitly render the `index` template like this:
+
+```ruby
+# a controller
+before_filter :choose_ab_test, only: :index, :archive
+
+def archive
+  render_ab template: 'index'
+end
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Versioned partials
+
+If instead of a full page template only a partial is going to be A/B Tested, you can achieve like this:
+
+```ruby
+# index.haml.html template
+= render_ab partial: 'menu', variable_for_the_partial: @variable
+```
+
+The pattern again here is to make 2 copies of the `_menu` partial and name them, i.e. `_menu_A` and `_menu_B`.
+
+### Versioned html snippets and partials
+
+Based on the variable `@ab_test` you can also make conditions in views and helpers:
+
+```ruby
+# index.haml.html template
+- if @ab_test == 'A'
+  version A is rendered
+- else
+  hello B
+```
+
+```ruby
+# a view helper
+def helper_method_AB_versioned
+  if @ab_test == 'A'
+    'version A is rendered'
+  else
+    'Hello B'
+  end
+end
+```
+
+### Several pages sharing the same A/B version
+
+Now imagine that the `index` actions of 2 controllers (e.g. `posts` and `authors`) are A/B versioned,
+and that you want that when an user sees version A of `posts#index` she should also see version A of `authors#index`.
+
+This can be achieved by overriding the method `choose_ab_test` in both controllers, and using a cookie:
+
+```ruby
+# posts controller
+before_filter :choose_ab_test, only: :index
+
+...
+
+def choose_ab_test
+  @ab_test = cookies['shared-version-posts-authors'] || super
+  cookies['shared-version-posts-authors'] = @ab_test
+end
+
+# authors controller should have the same code as above
+```
+
+Of course you can extract the common code to a central place. Also name the cookie with a name that makes sense for you, and expire it, sign it or encrypt it as needed.
+
+### Cookies to persist versions
+
+If an user should always see the same A/B version of a page, the same method above and a cookie work perfectly:
+
+```ruby
+# a controller
+before_filter :choose_ab_test, only: :index
+
+...
+
+def choose_ab_test
+  @ab_test = cookies['shared-version-posts-authors'] || super
+  cookies['shared-version-posts-authors'] = @ab_test
+end
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rails_ab_test.
+Bug reports and pull requests are welcome on GitHub at https://github.com/joahking/rails_ab_test.
 
+## TODOs
+
+- write tests
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/lib/rails_ab_test.rb

@@ -1,5 +1,6 @@
 require "rails_ab_test/version"
 
 module RailsAbTest
-  # Your code goes here...
+  autoload :Controller, 'rails_ab_test/controller'
+  autoload :Helper, 'rails_ab_test/helper'
 end

data/lib/rails_ab_test/controller.rb

@@ -0,0 +1,36 @@
+# Public: helper methods for ApplicationController to generate A/B testing version.
+#
+module RailsAbTest
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      include RailsAbTest::Helper
+      helper RailsAbTest::Helper
+    end
+
+    protected
+
+    # Internal: generates the AB version, i.e. randomly (50%) "A" or "B".
+    # Examples
+    #   before_filter :choose_ab_test or read README for other examples.
+    #
+    # The version s accessible in controllers, views and helpers as @ab_test.
+    #
+    # For testing/QA purposes: If the parameter ab_test=A is appended to the url,
+    #                          the version passed is used.
+    #
+    # TODO: should/can be extended to:
+    # - accept different probabilities of each version to e.g. 75%, 25%
+    #
+    def choose_ab_test(ab_tests: ['A', 'B'])
+      @ab_test = if ab_tests.include? params[:ab_test]
+                   # support to test/QA page versions
+                   params[:ab_test]
+                 else
+                   ab_tests.sample # randomize A/B Test version
+                 end
+    end
+
+  end
+end

data/lib/rails_ab_test/helper.rb

@@ -0,0 +1,29 @@
+# Public: helpers for your controllers and views.
+#
+module RailsAbTest
+  module Helper
+
+    # Public: renders A/B Test versions of same template/partial.
+    #
+    # options - hash to determine whether to render a template or a partial. Optional.
+    #           If not passed it renders a template by controller.action_name. Default.
+    #
+    # Examples:
+    #   to render a template use:
+    #     render_ab template: 'template_name'
+    #
+    #   to render a partial, the options hash can contain more keys:
+    #     render_ab partial: 'partial_name', variable: 'you name it'
+    #
+    def render_ab(options = {})
+      if options[:partial].present?
+        partial = options.delete(:partial)
+        render "#{partial}_#{@ab_test}", options
+      else
+        template = options[:template] || action_name
+        render "#{template}_#{@ab_test}"
+      end
+    end
+
+  end
+end

data/lib/rails_ab_test/version.rb

@@ -1,3 +1,3 @@
 module RailsAbTest
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_ab_test
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Joaquin Rivera Padron
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-10-10 00:00:00.000000000 Z
+date: 2016-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -68,6 +68,8 @@ files:
 - bin/console
 - bin/setup
 - lib/rails_ab_test.rb
+- lib/rails_ab_test/controller.rb
+- lib/rails_ab_test/helper.rb
 - lib/rails_ab_test/version.rb
 - rails_ab_test.gemspec
 homepage: https://github.com/joahking/rails_ab_test