Namespace Pollution Mechanism


    0.11.4 • Public • Published

    🤖  puppet-run

    npm (tag)

    Run any JavaScript / TypeScript code in a headless browser using Puppeteer and pipe its output to your terminal 🔥

    Transparently bundles input files, so you can use require() and ES module imports. You can even simulate connectivity issues and serve static files. Great for testing client-side code in an actual browser!

    How does it relate to Karma? It's everything that Karma is not: It's small, it's fast and trivial to set up.

    🚀  Runs any script in a headless Chrome browser
    📦  Zero-config transparent bundling
    💡  Supports TypeScript, ES modules & JSX out of the box
    🖥  Pipes console output and errors to host shell
    ⚙️  Uses custom Babel, TypeScript, ... config if present


    npm install puppet-run



    Running puppet-run from the command line is simple. We can use npm's npx tool for convenience.

    npx puppet-run [<arguments>]
    # without npx
    node ./node_modules/.bin/puppet-run [<arguments>]

    Pass any JavaScript or TypeScript file to puppet-run as an entrypoint. It will be transpiled by Babel and bundled using browserify. It normally works out-of-the-box with zero configuration.

    npx puppet-run [...puppet-run options] ./path/to/script.js [...script options]

    Run mocha tests

    npm install puppet-run-plugin-mocha
    npx puppet-run --plugin=mocha [...mocha options] ./path/to/*.test.js

    Print help texts

    npx puppet-run --help

    To print a plugin's help text:

    npx puppet-run --plugin=mocha --help


    // sample.js
    // Everything logged here will be piped to your host terminal
    console.log(`I am being run in a browser: ${navigator.userAgent}`)
    // Explicitly terminate the script when you are done

    Don't forget to call puppet.exit() when the script is done, so puppet-run knows that the script has finished. You can also exit with a non-zero exit code using puppet.exit(statusCode: number).

    Check out the "Scripting API" section below if you want to learn more about the globally available puppet object.

    Let's run the sample script!

    npx puppet-run ./sample.js

    You should now see the output of the script on your terminal:

    I am being run in a browser: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36

    Have fun!


    Plugins make it easy to integrate your script with testing frameworks.

    Check out the 👉 plugins repository to see what's on offer.

    Scripting API

    The script runner will inject a puppet object into the browser window's global scope. It contains a couple of useful functions.

    puppet.argv: string[]

    Contains all the command line arguments and options passed to puppet-run after the script file path.

    puppet.exit(exitCode?: number = 0)

    Causes the script to end. The puppet-run process will exit with the exit code you pass here.

    The exit code defaults to zero.

    puppet.setOfflineMode(takeOffline: boolean = true)

    Puts the browser in offline mode and closes all active connections if called with true or no arguments. Call it with false to bring the browser back online.

    More features

    Environment variables

    You can access all environment variables of the host shell in your scripts as process.env.*.

    Source Maps

    If an error is thrown, you will see the error and stack trace in your host shell. The stack trace will reference your source file lines, not the line in the bundle file that is actually served to the browser under the hood.


    Have a look at the samples in the sample directory:

    Test framework support

    If you want to run tests in the browser using puppet-run, check out this list first:


    Works like a charm, see sample/mocha or sample/mocha-enzyme. They use the Mocha Plugin.


    Works like a charm, see sample/tape.


    Currently not possible, since it's testing library and test runner code are too tightly coupled.


    Didn't try yet.




    npm i puppet-run

    DownloadsWeekly Downloads






    Unpacked Size

    87.2 kB

    Total Files


    Last publish


    • andywer