Unit-testing for those hard to reach places

  • floss

Downloads in past


5.0.12 years ago8 years agoMinified + gzip package size for floss in KB


Unit-testing for those hard to reach places.
Node.js CI npm version
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.


Install globally:
npm install -g floss electron

Install locally within a project:
npm install floss electron --save-dev

Debug Mode

Open tests in an Electron window where test can can be debugged with debugger and dev tools.
await floss({
    path: 'test/*.js',
    debug: true

Mocha Reporter

The reporter and reporterOptions are pass-through options for Mocha to specify a different reporter when running Floss in non-debug mode.
await floss({
    path: 'test/*.js',
    reporter: 'xunit',
    reporterOptions: {
    	filename: 'report.xml'

Custom Options

Additional properties can be passed to the test code by adding more values to the run options.
await floss({
    path: 'test/*.js',
    customUrl: 'http://localhost:8080' // <- custom

The test code and use the global options property to have access to the run options.
console.log(options.customUrl); // logs: http://localhost:8080

Electron Arguments

Commandline arguments can be passed to Electron directly by using args. In the example below, you may wan to disable Electron's user-gesture policy if you are testing HTML video or audio playback.
await floss({
    path: 'test/index.js',
    args: ['--autoplay-policy=no-user-gesture-required']

Command Line Usage


  • --path or -p (String) Path to the file to test
  • --debug or -d (Boolean) Enable to run in headful mode, default false.
  • --quiet or -q (Boolean) Prevent consolelog/info/error/warn/dir messages from appearing in stdout.
  • --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.
  • --require or -r (String) Module to require (e.g., ts-node/register).
  • -- args Additional arguments can be passed to Electron after --


Command Line usage when installed globally:
floss --path "test/*.js"

Or installed locally:
node node_modules/.bin/floss --path "test/*.js"

Alernatively, within the package.json's' scripts:
    "scripts": {
        "test": "floss --path \"test/*.js\""

Debug Mode

Open tests in an Electron window where test can can be debugged with debugger and dev tools.
floss --path "test/*.js" --debug

Using TypeScript

Support can easily be added for writing tests in TypeScript using ts-node.
floss --path "test/*.ts" --require ts-node/register

Istanbul Code Coverage

Floss supports nyc. To use it, just use floss as you would mocha:
nyc floss --path "test/*.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/*.js" \
    --reporter=xunit \
    --reporterOptions output=report.xml

Electron Arguments

Supports passing additional arguments to Electron after --.
floss --path "test/*.js" -- --autoplay-policy=no-user-gesture-required

Custom Electron Version

Some application may require a specific version of Electron. Floss uses Electron 10.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.
floss --path "test/.js" \
	--electron /usr/local/bin/electron

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

GitHub Actions Integration

name: Node.js CI
    branches: [ '**' ]
    tags: [ '**' ]
    runs-on: ubuntu-latest
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v1
        node-version: '12'
    - run: npm install
    - uses: GabrielBB/xvfb-action@v1.0
        run: npm test