Simple feature, multi-variant and A/B testing

npm install pivot
9 downloads in the last month

pivot Build Status

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.



npm install --save pivot


component install CamShaft/pivot

Lookup Strategies


Assignment Strategies



Start by initializing pivot

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

var experiments = pivot();

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


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);


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.


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


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);


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


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

// Variants, be default, are [false, true]

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


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.


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

 * 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.locals.features is now populated with all of the enabled features for the user.


npm install
npm test
npm loves you