react-ab-test

A/B Testing React Components

Wrap components in ](#variant-) and nest in [. A variant is chosen randomly and saved to local storage.

Report to your analytics provider using the emitter. Helpers are available for Mixpanel and Segment.com.

emitter.addPlayListener(function(experimentName, variantName){
  mixpanel.track("Start Experiment", {name: experimentName, variant: variantName});
});

Please ★ on GitHub!

Table of Contents

• Installation
• Usage
  • Standalone Component
  • Coordinate Multiple Components
  • Weighting Variants
  • Debugging
  • Server Rendering
    • Example
  • With Babel
• Alternative Libraries
• Resources for A/B Testing with React
• API Reference
  • ``
  • ``
  • emitter
    • emitter.emitWin(experimentName)
    • emitter.addActiveVariantListener([experimentName, ] callback)
    • emitter.addPlayListener([experimentName, ] callback)
    • emitter.addWinListener([experimentName, ] callback)
    • emitter.defineVariants(experimentName, variantNames [, variantWeights])
    • emitter.setActiveVariant(experimentName, variantName)
    • emitter.getActiveVariant(experimentName)
    • emitter.getSortedVariants(experimentName)
  • Subscription
    • subscription.remove()
  • experimentDebugger
    • experimentDebugger.enable()
    • experimentDebugger.disable()
  • mixpanelHelper
    • Usage
    • mixpanelHelper.enable()
    • mixpanelHelper.disable()
  • segmentHelper
    • Usage
    • segmentHelper.enable()
    • segmentHelper.disable()
• How to contribute
  • Requisites
  • Browser Coverage
  • Running Tests

Installation

react-ab-test is compatible with React 0.14.x and 0.15.x.

npm install react-ab-test

Usage

Standalone Component

Try it on JSFiddle

…

Coordinate Multiple Components

Try it on JSFiddle

…

Weighting Variants

Try it on JSFiddle

Use emitter.defineVariants() to optionally define the ratios by which variants are chosen.

var Experiment = require("react-ab-test/lib/Experiment");
var Variant = require("react-ab-test/lib/Variant");
var emitter = require("react-ab-test/lib/emitter");

// Define variants and weights in advance.
emitter.defineVariants("My Example", ["A", "B", "C"], [10, 40, 40]);

var App = React.createClass({
  render: function(){
    return 

        
        
          

        
        
          

        
      
    ;
  }
});

Debugging

The debugger attaches a fixed-position panel to the bottom of the `` element that displays mounted experiments and enables the user to change active variants in real-time.

The debugger is wrapped in a conditional if(process.env.NODE_ENV === "production") {...} and will not display on production builds using envify.

Try it on JSFiddle

var Experiment = require("react-ab-test/lib/Experiment");
var Variant = require("react-ab-test/lib/Variant");
var experimentDebugger = require("react-ab-test/lib/debugger");

experimentDebugger.enable();

var App = React.createClass({
  render: function(){
    return 

        
        
          

        
      
    ;
  }
});

Server Rendering

A ](#experiment-) with a `userIdentifier` property will choose a consistent [ suitable for server side rendering.

See ./examples/isomorphic for a working example.

Example

The component in Component.jsx:

var React = require("react");
var Experiment = require("react-ab-test/lib/Experiment");
var Variant = require("react-ab-test/lib/Variant");

module.exports = React.createClass({
  propTypes: {
    userIdentifier: React.PropTypes.string.isRequired
  },
  render: function(){
    return 

        
        
          

        
      
    ;
  }
});

We use a session ID for the userIdentifier property in this example, although a long-lived user ID would be preferable. See server.js:

…

Remember to call abEmitter.rewind() to prevent memory leaks.

An EJS template in template.ejs:

  
    Isomorphic Rendering Example
  
  

  
    

    

  

On the client in app.jsx:

var React = require('react');
var ReactDOM = require('react-dom');
var Component = require("../Component.jsx");

var container = document.getElementById("react-mount");

ReactDOM.render(, container);

With Babel

Code from ./src is written in JSX and transpiled into ./lib using Babel. If your project uses Babel you may want to include files from ./src directly.

Alternative Libraries

• react-experiments - “A JavaScript library that assists in defining and managing UI experiments in React” by Hubspot. Uses Facebook's PlanOut framework via Hubspot's javascript port.
• react-ab - “Simple declarative and universal A/B testing component for React” by Ola Holmström
• react-native-ab - “A component for rendering A/B tests in React Native” by Loch Wansbrough

Please let us know about alternate libraries not included here.

Resources for A/B Testing with React

• Product Experimentation with React and PlanOut on the HubSpot Product Blog
• Roll Your Own A/B Tests With Optimizely and React on the Tilt Engineering Blog
• Simple Sequential A/B Testing
• A/B Testing Rigorously (without losing your job)

Please let us know about React A/B testing resources not included here.

API Reference

``

Experiment container component. Children must be of type Variant.

• Properties:
  • name - Name of the experiment.
    • Required
    • Type: string
    • Example: "My Example"
  • userIdentifier - Distinct user identifier. When defined, this value is hashed to choose a variant if defaultVariantName or a stored value is not present. Useful for server side rendering.
    • Optional
    • Type: string
    • Example: "7cf61a4521f24507936a8977e1eee2d4"
  • defaultVariantName - Name of the default variant. When defined, this value is used to choose a variant if a stored value is not present. This property may be useful for server side rendering but is otherwise not recommended.
    • Optional
    • Type: string
    • Example: "A"

``

Variant container component.

• Properties:
  • name - Name of the variant.
    • Required
    • Type: string
    • Example: "A"

emitter

Event emitter responsible for coordinating and reporting usage. Extended from facebook/emitter.

emitter.emitWin(experimentName)

Emit a win event.

• Return Type: No return value
• Parameters:
  • experimentName - Name of an experiment.
    • Required
    • Type: string
    • Example: "My Example"

emitter.addActiveVariantListener([experimentName, ] callback)

Listen for the active variant specified by an experiment.

• Return Type: Subscription
• Parameters:
  • experimentName - Name of an experiment. If provided, the callback will only be called for the specified experiment.
    • Optional
    • Type: string
    • Example: "My Example"
  • callback - Function to be called when a variant is chosen.
    • Required
    • Type: function
    • Callback Arguments:
      • experimentName - Name of the experiment.
        • Type: string
      • variantName - Name of the variant.
        • Type: string

emitter.addPlayListener([experimentName, ] callback)

Listen for an experiment being displayed to the user. Trigged by the React componentWillMount lifecycle method.

• Return Type: Subscription
• Parameters:
  • experimentName - Name of an experiment. If provided, the callback will only be called for the specified experiment.
    • Optional
    • Type: string
    • Example: "My Example"
  • callback - Function to be called when an experiment is displayed to the user.
    • Required
    • Type: function
    • Callback Arguments:
      • experimentName - Name of the experiment.
        • Type: string
      • variantName - Name of the variant.
        • Type: string

emitter.addWinListener([experimentName, ] callback)

Listen for a successful outcome from the experiment. Trigged by the emitter.emitWin(experimentName) method.

• Return Type: Subscription
• Parameters:
  • experimentName - Name of an experiment. If provided, the callback will only be called for the specified experiment.
    • Optional
    • Type: string
    • Example: "My Example"
  • callback - Function to be called when a win is emitted.
    • Required
    • Type: function
    • Callback Arguments:
      • experimentName - Name of the experiment.
        • Type: string
      • `variant