= Vanity
{<img src="https://travis-ci.org/assaf/vanity.png?branch=master" alt="Build Status" />}[https://travis-ci.org/assaf/vanity]

Vanity is an Experiment Driven Development framework for Rails.

* All about Vanity: http://vanity.labnotes.org
* On Github: http://github.com/assaf/vanity

http://farm3.static.flickr.com/2540/4099665871_497f274f68_o.jpg


== A/B Testing With Rails (In 5 Easy Steps)

=== <b>Step 1:</b> Start using Vanity in your Rails application

==== Step 1.1

===== Rails 2.x installation

  Rails::Initializer.run do |config|
    gem.config "vanity"

    config.after_initialize do
      require "vanity"
    end
  end

===== Rails 3 & Rails 4 installation

Add to your Gemfile:

  gem "vanity"

==== Step 1.2

Choose a method to store experiment results: for Redis or an external tracking mechanism, migrations aren't needed. Mongo is also available. To use a relational database, via ActiveRecord, run the generator and migrations to create the database schema:

  $ rails generate vanity
  $ rake db:migrate

==== Step 1.3

add to your application controller:

  class ApplicationController < ActionController::Base
    use_vanity :current_user
  end

=== <b>Step 2:</b> Define your first A/B test

This experiment goes in the file <code>experiments/price_options.rb</code>:

  ab_test "Price options" do
    description "Mirror, mirror on the wall, who's the better price of all?"
    alternatives 19, 25, 29
    metrics :signups
  end

NOTE: If using a metric as above ("signups"), there needs to be a corresponding ruby file for that metric. Inside the "experiments" directory create a "metrics" directory with a file called "signups.rb". The contents of the file can describe the signup metric, refer to the "Metrics" Vanity documentation page for an example.

=== <b>Step 3:</b> Present the different options to your users

  <h2>Get started for only $<%= ab_test :price_options %> a month!</h2>

=== <b>Step 4:</b> Measure conversion

Conversions are created via the <code>track!</code> method. For example:

  class SignupController < ApplicationController
    def signup
      @account = Account.new(params[:account])
      if @account.save
        track! :signups
        redirect_to @acccount
      else
        render action: :offer
      end
    end
  end

=== <b>Step 5:</b> Check the report:

  vanity report --output vanity.html

To view metrics and experiment results with the dashboard in Rails 3 & Rails 4:

  rails generate controller Vanity

In <code>config/routes.rb</code>, add:

  match '/vanity(/:action(/:id(.:format)))', :controller => :vanity, :via => :get

Where the controller should looks like:

  class VanityController < ApplicationController
    include Vanity::Rails::Dashboard
  end

NOTE: By default, Vanity turns collection off in development mode. To turn it on, in <code>config/environments/development.rb</code> add:

  Vanity.playground.collecting = true

== Registering participants with Javascript

If robots or spiders make up a significant portion of your sites traffic they can affect your conversion rate.  Vanity can optionally add participants to the experiments using asynchronous javascript callbacks, which will keep almost all robots out.  To set this up simply do the following:

* Add <code>Vanity.playground.use_js!</code>
* Set <code>Vanity.playground.add_participant_path = '/path/to/vanity/action'</code>, this should point to the add_participant path that is added with Vanity::Rails::Dashboard, make sure that this action is available to all users
* Add <code><%= vanity_js %></code> to any page that needs uses an ab_test. <code>vanity_js</code> needs to be included after your call to ab_test so that it knows which version of the experiment the participant is a member of. The helper will render nothing if the there are no ab_tests running on the current page, so adding <code>vanity_js</code> to the bottom of your layouts is a good option. Keep in mind that if you call <code>use_js!</code> and don't include <code>vanity_js</code> in your view no participants will be recorded.

== Compatibility

Here's what's tested and known to work:

  Ruby 1.8.7
    Persistence: Redis, Mongo, ActiveRecord
    Rails: 2.3, 3, 3.1, 3.2
  Ruby 1.9.3
    Persistence: Redis, Mongo, ActiveRecord
    Rails: 3, 3.1, 3.2, 4.0
  Ruby 2.0
    Persistence: Redis, Mongo, ActiveRecord
    Rails: 3.2, 4.0

== Testing

For view tests/specs or integration testing, it's handy to set the outcome of an experiment. This may be done using the <code>chooses</code> method. For example:

  Vanity.playground.experiment(:price_options).chooses(19)

== Contributing

* Fork the project
* Please use a topic branch to make your changes, it's easier to test them that way
* To set up the test suite run bundler, then run `rake appraisal:install` to prepare the test suite to run against multiple versions of Rails
* Fix, patch, enhance, document, improve, sprinkle pixie dust
* At minimum run `rake appraisal test`, if possible, please run rake test:all
* Tests. Please. Run rake test, of if you can, rake test:all
* Send a pull request on GitHub


== Credits/License

Original code, copyright of Assaf Arkin, released under the MIT license.

Documentation available under the Creative Commons Attribution license.

For full list of credits and licenses: http://vanity.labnotes.org/credits.html.