README

varsnap.js

Javascript Varsnap Client. For use in both browser and node.js

Installation

Install from NPM - npm install --save varsnap

Configuration

The varsnap decorator needs to be configured with a config object with these variables:

varsnap - Should be either true or false. Varsnap will be disabled if the variable is anything other than true.
env - If set to development, the client will receive events from production. If set to production, the client will emit events.
branch - Used for labeling test runs by (git) branch. Test runs on the master branch will update your varsnap badge
producerToken - Only clients with this token may emit production snapshots. Copied from https://www.varsnap.com/user/
consumerToken - Only clients with this token may emit development snapshots. Copied from https://www.varsnap.com/user/

If you're deploying varsnap to a browser, note that Varsnap needs unmangled code in production to work correctly.

Usage

Wrap your functions with the varsnap decorator for any function you'd like to make better:

// Node.js
var varsnap = require('varsnap');

// Browser
var varsnap = window.varsnap;

// Configuration
varsnap.updateConfig({
  varsnap: true,
  env: 'production',
  branch: 'master',
  producerToken: 'producer-abcd'
});

// Integration
function example(x, y, z) {
  // ...
}
example = varsnap(example);

example(1, 2, 3);

See example/example.js for example usage.

Typescript

If you are using typescript, make sure your tsconfig.json has a "target" to "es2015", "es6", or later. This is needed to persist function names after compiling to javascript. See https://github.com/microsoft/TypeScript/issues/5611 for details.

Testing

Use the varsnap.runTests() function.

function test() {
  const status = varsnap.runTests().then(function(status) => {
    console.assert(status);
  });;
}

If you are using mocha and chai, you can include this test script:

const expect = require('chai').expect;
const varsnap = require('varsnap');

// Load the modules where varsnap is being used
require('./example');

context('Varsnap', function() {
  this.timeout(30 * 1000);
  it('runs with production', function() {
    return varsnap.runTests().then(status => {
      expect(status).to.be.true;
    });
  });
});

See example/test.js for example usage.

Minification/Obfuscation

This client currently does not work with minification/obfuscation libraries that change class, function, and argument names. Disable any code processors that change these names. If you are using the terser package, use these configuration options to allow the varsnap client to match production and development Snaps together:

const { minify } = require('terser');

const options = {
  mangle: false,
  keep_fnames: true,
  keep_classnames: true,
}
minify(code, options);

Git Branch

Providing a git branch to the client allows Varsnap to categorize test runs. Tests on the master branch will also be reflected in your Varsnap badge image.

For builds in environments that cannot access git branch names, such as builds in headless browsers, varsnap/gitbranchenv.ts will read git branch names and set them into a GIT_BRANCH environment variable. This can then be copied into the varsnap config when testing.

Client Development

Release

Update Changelog with new version
Update const version in varsnap/core.ts
Update package.json version and run npm install
Update .uglify.json and .uglify.min.json
Run npm run package
Git commit, tag, and push
Upload dist/* to https://github.com/albertyw/varsnap.js/releases

Usage no npm install needed!