Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    smokestackpublic

    smokestack

    JavaScript goes in, console logs come out.

    NPM

    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 the interface 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 run tape in the browser and get TAP output in your terminal.

    CLI Usage

    Most of the time, you'll want to use smokestack using the command-line interface, which accepts JavaScript on stdin. For example, to run any arbitrary JavaScript file:

    smokestack < script.js

    You can include smokestack in the middle of your pipeline too. Here's an example of using browserify and tape to run a test on Firefox, using tap-spec for formatting:

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

    This works because any calls to console.log and its variants are sent back from the browser out to the other side of the smokestack process.

    Usage:
      smokestack {OPTIONS} < script.js
    
    General:
      -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 message
    
    Sauce 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
    

    Browser Usage

    console.log

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

    window.close

    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 that happen automatically when it's ready.

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

    smokestack = require('smokestack')

    For any optional extras which don't have a native browser analogue, you can pull in smokestack using browserify.

    smokestack.capture(dest, done)

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

    Images will be saved as PNGs.

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

    Module Usage

    stream = smokestack(opts)

    Creates a new smokestack stream. You should pipe JavaScript into it, and pipe the console output somewhere else, much the same as you would when using the command-line:

    var smokestack = require('smokestack')
    var fs         = 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.

    Sauce Labs

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

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

    Your username/key will also get picked up from your environment if they're defined too, so feel free to include the following in your ~/.bash_profile and 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'

    Headless Browsers

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

    For example, on recent Debian linux:

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

    See Also

    • tap-closer -- close the browser window once TAP tests have finished

    License

    MIT. See LICENSE.md for details.

    install

    npm i smokestack

    Downloadsweekly downloads

    25

    version

    3.4.1

    license

    MIT

    repository

    githubgithub

    last publish

    collaborators

    • avatar
    • avatar
    • avatar