TypeScript icon, indicating that this package has built-in type declarations

    5.0.1 • Public • Published


    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 console[log/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


    npm i floss

    DownloadsWeekly Downloads






    Unpacked Size

    38.8 kB

    Total Files


    Last publish


    • marstonstudio
    • squiddisco
    • wwlib
    • jibo-jonathan
    • justin-perez
    • golgobot
    • mividtim
    • francoislaberge
    • bigtimebuddy
    • andrewstart
    • mbittarelli