Repository files navigation

Pipe your JavaScript into a browser of your choosing:

• Local Google Chrome.
• Local Mozilla Firefox.
• Sauce Labs for the rest.

A simple alternative to bigger browser automation tools, aiming to keep theinterface and initial setup as simple as possible: JavaScript goes in,console logs come out. There's also support for browser screenshots in Chrome,with the other browsers getting support for that soon too.

Designed for running UI tests on your desktop machine. You can use this,for example, to runtape in the browser andget TAP output in your terminal.

Most of the time, you'll want to usesmokestack using the command-lineinterface, which accepts JavaScript on stdin. For example, to run any arbitraryJavaScript file:

smokestack< script.js

You can includesmokestack in the middle of your pipeline too. Here's anexample of usingbrowserify andtape to run a test on Firefox, usingtap-spec for formatting:

browserify test.js| smokestack -b firefox| tap-spec

This works because any calls toconsole.log and its variants are sent backfrom the browser out to the other side of thesmokestack process.

Usage:  smokestack {OPTIONS} < script.jsGeneral:  -b, --browser  Specify which browser to use [default: chrome]  -t, --timeout  Specify the maximum timeout in milliseconds  -p, --port     Specify a port for smokestack to listen to  -h, --help     Display this messageSauce Labs only:  -s, --saucelabs  Include to run your tests on Sauce Labs  -u, --username   Username to log in with  -k, --key        API Access key to use

console.log and its variants are all instrumented such that they not onlylog output to your console, but to the other side of the smokestack processin your Terminal too! You can use these methods the way you're familiarwith them in node or your favourite browser, they'll work just the same.

window.close is instrumented by smokestack to trigger the end of a run.In most cases, you don't want to manually close the browser and have thathappen automatically when it's ready.

Just use this method when you've done what you wanted to do, and it'll tellChrome/Firefox/Sauce Labs to shut down (relatively) gracefully.

For any optional extras which don't have a native browser analogue, you canpull insmokestack usingbrowserify.

Takes a screenshot of the current browser window, writing out the captured filetodest. Currently only works on Chrome, but eventually this will be availableon Firefox and Sauce Labs too.

Images will be saved as PNGs.

varsmokestack=require('smokestack')window.onload=function(){smokestack.capture('screenshots/0001.png',function(err){if(err)throwerrwindow.close()})}

Creates a new smokestackstream. You should pipe JavaScript into it, andpipe the console output somewhere else, much the same as you would when usingthe command-line:

varsmokestack=require('smokestack')varfs=require('fs')fs.createReadStream('script.js').pipe(smokestack({browser:'chrome',timeout:15000,saucelabs:false})).pipe(process.stdout)

opts are equivalent to what's used in the command-line interface.

Using Sauce Labs with smokestack is simple, simply include the followingadditional arguments:

smokestack --saucelabs --username USERNAME --key ACCESS_KEY

Your username/key will also get picked up from your environment if they'redefined too, so feel free to include the following in your~/.bash_profileand omit the--username and--key flags:

# Obviously, include your own, non-fake credentials here:export SAUCE_USERNAME='hughskennedy'export SAUCE_ACCESS_KEY='138b247bc5b6-b14b-a4d4-agcf-82c460a2'

You may be able to run a browser headlessly using anX virtual frame buffer.

For example, on recent Debian linux:

# Install Xvfb from Debian Repositorysudo apt-get updatesudo apt-get install -y xvfb# Install Google Chrome to google-chromewget -c wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.debsudo dpkg -i google-chrome-stable_current_amd64.debsudo ln -s$(which google-chrome-stable) /usr/bin/google-chrome# Start a virtual framebuffer displayXvfb :1 -screen 5 1024x768x8&export DISPLAY=:1.5# Run tests in Chromenpm run test:chrome

• tap-closer -- close the browserwindow once TAP tests have finished

MIT. SeeLICENSE.md for details.