README.md

pivot

pivot is a simple feature multi-variant and A/B testing framework for node and component.

It is designed to have a pluggable backend and provide a common interface to each testing strategy.

Installing

node

npm install --save pivot

component

component install CamShaft/pivot

Lookup Strategies

TODO

Assignment Strategies

TODO

Guide

Start by initializing pivot

/**
 * Module dependencies
 */
var pivot = require("pivot");

var experiments = pivot();

You'll need to tell it about the following methods:

lookup

This method looks up the variant settings in the backend. It is called any time pivot encounters a new feature.

experiments.lookup(function(name, variants, done){
  /**
   * We can do a few things here:
   *
   *   * Lookup our feature settings locally
   *   * If we dont have it, notify an admin control panel page
   *   * Log outdated features; either ones that should be integrated or ones that should be removed
   */

  var settings = []; // can come from anywhere: database, REST api, local json file, etc

  done(null, settings);
});

assign

This method takes the settings from the last call and assigns them to a user.

experiments.assign(function(name, settings, user, done){
  /**
   * If the variant is a group, we can inspect the `user` object to check where they fall
   * If the variant is a weight, we can implement our own random assignment algorithm
   *
   * The callback expects the name of the variant chosen for the given user
   */

  // For this example we're just going to assign the first variant to everyone
  done(null, settings[0]);
});

If you plan on using it paired with express/connect, you can also define the following. Otherwise, pivot will serialize/deserialize using the pivot cookie and req.user.

serialize

experiments.serialize(function(features, req, res, next){
  // Save the features for the user
  next();
});

deserialize

experiments.deserialize(function(req, res, next){
  // Retrieve the features for the request
  var features = {}; // can come from anywhere i.e. cookies, session, database
  next(null, features);
});

findUser

experiments.findUser(function(req, res, next){
  // Give the user for the request to pivot
  next(null, req.user);
});

feature

Once you have told pivot how to do things you can start adding features into the system:

// Variants, be default, are [false, true]
experiments.feature("my-cool-test");

// You can also add multi-variant
experiments.feature("my-other-test", ["blue", "red", "green"]);

variant

Now you can ask pivot to assign a variant to a user:

var user = {}; // pull from your user info

experiments.variant("my-cool-test", user, function(err, variant){
  // do something based on the value of variant
})

variant is either true or false depending on how we implemented the assign method.

handle

If you are using express/connect pivot comes with some batteries included:

/**
 * Module dependencies
 */
var express = require("express")
  , pivot = require("pivot");

/**
 * Create our server and experiments
 */
var app = module.exports = express()
  , experiments = pivot();

/**
 * Add our experiment setup to express
 */
app.use(experiments);

/**
 * Configure pivot here with the required methods
 */
...

experiments.feature("landing-page", ["minimal", "fancy"]);

app.get("/", function(req, res, next){
  var view = res.locals.features["landing-page"]; // either "minimal" or "fancy"
  res.render(view);
});

res.locals.features is now populated with all of the enabled features for the user.

Testing

npm install
npm test