floss

Floss

Unit-testing for those hard to reach places.

Uses Electron to provide a Mocha unit-testing environment which can be run headlessly or to debugged with DevTools. This was largely inspired by the electron-mocha and mocha-electron projects but didn't quite have the debugging features needed to develop tests.

Installation

Install globally:

npm install -g floss electron-prebuilt

Install locally within a project:

npm install floss electron-prebuilt --save-dev

Gulp Usage

const floss = require('floss');
gulp.task('test', function(done) {
    floss('test/index.js', done);
});

Debug Mode

Open tests in an Electron window where test can can be debugged with debugger and dev tools.

floss({
    path: 'test/index.js',
    debug: true
}, done);

Mocha Reporter

The reporter and reporterOptions are pass-through options for Mocha to specify a different reporter when running Floss in non-debug mode.

floss({
    path: 'test/index.js',
    reporter: 'xunit',
    reporterOptions: {
    	filename: 'report.xml'
    }
}, done);

Custom Options

Additional properties can be passed to the test code by adding more values to the run options.

floss({
    path: 'test/index.js',
    customUrl: 'http://localhost:8080' // <- custom
}, done);

The test code and use the global options property to have access to the run options.

console.log(options.customUrl); // logs: http://localhost:8080

Command Line Usage

Arguments

• --path or -p (String) Path to the file to test
• --debug or -d (Boolean) Enable to run in headful mode, default false.
• --electron or -e (String) Path to the electron to use.
• --reporter or -r (String) Mocha reporter type, default spec.
• --reporterOptions or -o (String) Mocha reporter options.
• --coveragePattern or -c (String) Glob pattern of file source to messure for coverage.
• --coverageHtmlReporter or -h (Boolean) Generatel HTML report for coverage, default false.
• --coverageSourceMaps or -s (Boolean) Use sourcemaps to determine coverage, default false.

Usage

Command Line usage when installed globally:

floss --path test/index.js

Or installed locally:

node node_modules/.bin/floss --path test/index.js

Alernatively, within the package.json's' scripts:

{
    "scripts": {
        "test": "floss --path test/index.js"
    }
}

Debug Mode

Open tests in an Electron window where test can can be debugged with debugger and dev tools.

floss --path test/index.js --debug

Istanbul Code Coverage

Floss comes with istanbul integration. This will generate a json report.

floss --path test/index.js --coveragePattern lib/**/*/*.js

To remap the json report using sourcemaps

floss --path test/index.js --coveragePattern lib/**/*/*.js --coverageSourceMaps

To generate an additional html report

floss --path test/index.js \
    --coveragePattern lib/**/*/*.js \
    --coverageHtmlReporter

To generate an additional html report with source maps

floss --path test/index.js \
    --coveragePattern lib/**/*/*.js \
    --coverageSourceMaps \
    --coverageHtmlReporter

For lists of globs put the coverage files in quotes comma or space separated

floss --path test/index.js \
    --coveragePattern "lib/**/*/*.js, node_modules/thing/lib/thing.js"

Mocha Reporter

Can use the same reporter options as the API mentioned above. The reporterOptions are expressed as a querystring, for instance varname=foo&another=bar.

floss --path test/index.js \
    --reporter=xunit \
    --reporterOptions output=report.xml

Custom Electron Version

Some application may require a specific version of Electron. Floss uses Electron 1.0.0+, but you can specific the path to your own version. The custom version can be used either through the commandline argument --electron, by setting the Node environmental variable ELECTRON_PATH or by setting the run option electron.

gulp.task('test', function(done) {
    floss({
        path: 'test/index.js',
        electron: require('electron-prebuilt')
    }, done);
});

floss --path test/index.js \
	--electron /usr/local/bin/electron

ELECTRON_PATH=/usr/local/bin/electron floss --path test/index.js

Travis Integration

Floss can be used with Travis CI to run Electron headlessly by utilizing Xvfb. Here's a sample of how to setup this project.

package.json

Note that scripts test must be setup in your package.json;

{
    "scripts": {
        "test": "gulp test"
    }
}

.travis.yml

language: node_js
node_js:
    - "4"

install:
    - npm install xvfb-maybe
    - npm install

before_script:
  - export DISPLAY=':99.0'
  - Xvfb :99 -screen 0 1024x768x24 -extension RANDR &

script:
    - xvfb-maybe npm test