Connect to BrowserStack's Local Testing Tunnel with Grunt

BrowserStack is a great tool for testing against multiple browsers and operating systems. On their live testing plans, they will spin up a server running the specified OS and browser and allow you to remotely interact. They also offer a screenshot service that will send you shots of your page in up to 25 browsers across desktop and mobile.

Local testing is handled via tunneling from the service to your local machine. This can be conveniently done with a Java applet that runs in the browser. As easy as this is to use, I've found the Java tunnel unreliable. I frequently have to reconnect in order to get access to my local development server.

BrowserStack offers a Java application which can be run locally that is much more reliable but requires a number of shell parameters to get it started. You could always do this with a shell script, but I like to keep all my automation in one place. To this end, I set up a Grunt task to run the script for me. It's a simple process to get it set up. I'm assuming you already have Grunt installed and working. If not, head over to the Grunt Getting Started page.

Install Jake Harding's grunt-exec. This will allow Grunt to run shell commands. Use npm install grunt-exec --save-dev to install it and add it to your package.json file.

Download BrowserStack's Java app for tunneling. Get it from their local testing page. You can put this anywhere. I simply added it to the root directory of my project. That makes the Grunt configuration a bit easier.

Add this new task to your Gruntfile's initConfig:

exec: {
  bstack_test: {
    cmd: 'java -jar BrowserStackTunnel.jar <your BrowserStack API key> localhost,<port>,0'
  }
}

That's all the code you need to make this work. However, having your BrowserStack API key in plain text in your Grunt file won't work in many cases. What I do instead is export an environmental variable at my shell and use that in the command. Change the command in your task configuration like so:

cmd: 'java -jar BrowserStackTunnel.jar $BROWSERSTACK_API localhost,<port>,0'

and export the variable from the terminal with the following command.

export BROWSERSTACK_API='<your BrowserStack API key>'

Now, your secret key will be safely out of version control and away from prying eyes.

(Optional) Create an alias for your task or include it in an existing task you have for testing and debugging. If you do add this to an existing task, take note it will block, so you need to have some way to run tasks concurrently. I have this task inside my initConfig:

grunt.registerTask('test', ['exec:bstack_test'])

Assuming you followed the optional step, just run this task from the terminal inside your project directory.

grunt test

You'll now have access to your local sites for testing on the plethora of browsers and devices offered by the BrowserStack service.