varsnap.js
==========

[![Build Status](https://drone.albertyw.com/api/badges/albertyw/varsnap.js/status.svg)](https://drone.albertyw.com/albertyw/varsnap.js)
[![Maintainability](https://qlty.sh/badges/a8d318bb-41fa-4373-b3f1-e4ae7a4be9db/maintainability.svg)](https://qlty.sh/gh/albertyw/projects/varsnap.js)
[![Code Coverage](https://qlty.sh/badges/a8d318bb-41fa-4373-b3f1-e4ae7a4be9db/coverage.svg)](https://qlty.sh/gh/albertyw/projects/varsnap.js)
[![install size](https://packagephobia.com/badge?p=varsnap)](https://packagephobia.com/result?p=varsnap)

[Javascript Varsnap Client](https://www.varsnap.com/).  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:

```javascript
// Node.js
// var varsnap = require('varsnap');
import varsnap from '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.

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

If you are using [mocha](https://mochajs.org/) and [chai](https://www.chaijs.com/),
you can include this test script:

```javascript
import { expect } from 'chai';
import varsnap from 'varsnap';

// Load the modules where varsnap is being used
import './example.js';

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](https://github.com/terser/terser#minify-options)
package, use these configuration options to allow the varsnap client to match
production and development Snaps together:

```javascript
import { minify } from '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.

Client Development
------------------

### Release

1.  Update Changelog with new version
2.  Update `const version` in `varsnap/core.ts`
3.  Update webpack.config.js version and run `pnpm run package`
4.  Update package.json version and run `pnpm install`
5.  Git commit, tag, and push
6.  Upload `dist/*` to https://github.com/albertyw/varsnap.js/releases