Puppet-run NPM

🤖 puppet-run

Run anything JavaScript in Chrome with puppeteer and pipe it's output back to your terminal 🔥

Transparently bundles your input files and runs them in a headless Chromium browser. Great for running tests 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 📦 Zero-config transparent bundling ⚙️ Uses existing Babel, TypeScript, ... config if present 💡 Supports TypeScript, ES modules & JSX out of the box 🖥 Pipes console output and errors to host shell

Installation

npm install puppet-run

We can use npm's npx tool to run the locally installed puppet-run program:

npx puppet-run [<arguments>]

# equal to:
# node ./node_modules/.bin/puppet-run [<arguments>]

Usage

Basics

npx puppet-run ./path/to/script.js [arguments and options here will be passed to the script]

The script can be any JavaScript or TypeScript file. It will be transparently transpiled via Babel using @babel/preset-env, @babel/preset-react & @babel/preset-typescript and bundled using browserify. It usually works out-of-the-box with zero configuration.

You just need to call puppet.exit() or optionally puppet.exit(statusCode: number) when the script is done, so puppet-run knows that the script is finished. The puppet object is a global, injected by puppet-run.

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

Print help text how to use this plugin:

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

Example

This is how a simple script might look like:

import { detect } from "detect-browser"

const browser = detect()

// You can use window.*, since this will be run in Chrome
const text = window.atob("SSBydW4gaW4gYSBicm93c2Vy")

// Everything logged here will be piped to your host terminal
console.log(text)
console.log(`I am being run in a ${browser.name} ${browser.version}`)

// Explicitly terminate the script when you are done
puppet.exit()

Recognize the final puppet.exit()? You need to tell puppet-run when the script has finished.

Have a look at the section "Scripting API" below to learn more about that globally available puppet object.

Let's run the sample script!

npm install detect-browser puppet-run
npx puppet-run ./sample.js

I live in a browser now
I am being run in a chrome 75.0

Have fun!

Plugins

Plugins make it easy to integrate your script with testing frameworks or other extra functionality.

Check out the 👉 plugins repository.

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.