BrowserStig = Developer Friendly Browser Automation

Docs

Getting Started

1. After installing browserstig, create a new directory:

   mkdir automation

   cd automation

2. Initialize your project with a browserstig.conf.js configuration file and a main.js start file:

   stig init

3. Run the sample test by running "stig" from the command-line with no options:

   stig

Config

BrowserStig requires a browserstig.conf.js to be in the same directory that you run the "stig" CLI. The following options are supported:

• browser: Specifies which browser to automate. Options include: 'Chrome', 'ChromeCanary', 'Firefox', 'Opera', 'Safari', 'PhantomJS' or 'IE' (Windows only).
• automatedUrl: This is the url/server that you will automate with browserstig.
• basePath: This is the path where your files are resolved from.
• main: This is either a js or a coffee file that will be loaded into the browser before other files.
• files: This is an array of js or coffee files that will run after the main file. Pattern matching is supported. ie. tests/*Test.js.
• exclude: This is an array of js or coffee files to be excluded from your list of files.
• framework: The test runner to load into the browser. Options are 'mocha', 'jasmine', or 'qunit'.
• reporters: An array of test reporters to specify how the tests should be reported. Options are 'dots', 'progress', 'junit', or 'growl'.

BrowserStig API

browserstig.js is automatically included in the BrowserStig automation environment. This gives you access to the BrowserStig global in any of your js or coffee files that you include. However, you could also include browserstig.js standalone in any project.

• constructor: You initialize BrowserStig using the new operator:

  var stig = new BrowserStig();

  
  You can also initialize a BrowserStig object with options:

  var stig = new BrowserStig({
    initialUrl: '/someurl', // defaults to '/'
    waitForElementTimeout: 30000 // The length of time (ms) to search for an element before timeout
  });
  

• open: Opens a url in the browserstig automation environment. The url must be relative to the automatedUrl in the browserstig.conf.js:

  stig.open('/search');

• run: Runs all of the queued actions and operations on elements. IMPORTANT! No actions will happen unless you call run last:

  stig.open('/search');
  stig.el('#searchbox').type('Dockers Jeans');
  stig.el('#go-button').click();
  stig.el('.search-result:first').text( function(text) {
    assert(text.indexOf('Skinny Jeans') !== -1);
  });
  stig.run();
  

  
  The run function also accepts a callback for when all of the actions have been completed:

  ...
  stig.run( function() {
    console.log('I'm done!');
  });
  

• setCookie: Sets the cookie in the browserstig automation environment.:

  stig.setCookie('authtoken=j43JasHlsa');

• el: Selects an element in the BrowserStig automation environment. You can pass it a jquery css selector string.:

  stig.el('#button').click();

• el.click: Click the selected element (refer to above example).
• el.type: Types the string into the selected input (or contenteditable) element:

  stig.el('#search').type('Books by J.K. Rowling');

• el.typeKey: Types the key into the selected input (or contenteditable) element. Keys are specified using the keyCodes enum on the BrowserStig object:

  stig.el('#search').type(BrowserStig.keyCodes.ENTER);

• el.hover: Hover over the selected element:

  stig.el('.dropdown').hover();

• el.value: Get the value of the selected input element. The value is returned in a callback function.:

  stig.el('#input').value( function(value) {
    assert(value === 'The text I entered');
  });

• el.count: Returns the number of elements that match the selector. The count is returned in a callback function:

  stig.el('li').count( function(count) {
    assert(count > 10);
  });

• el.text: Returns the inner text of the selected element. The text is returned in a callback function:

  stig.el('title').text( function(text) {
    assert(text.indexOf('Amazon') !== -1);
  });

• el.get: Returns the jquery element from the given selector. The element is returned in a callback function:

  stig.el('.content').get( function(el) {
    assert(el.html().indexOf('title') !== -1);
  });

Functional Testing with BrowserStig

Although BrowserStig may be used for other automation purposes, it's main purpose is to be used for functional testing. As mentioned before, you can use browserstig.js standalone without the cli. This would allow you to import browserstig.js into any javascript testing framework. However, the stig cli is designed to help you start testing immediately with minimal setup.

If you have used the karma test runner, you will be familiar with the stig cli. Really, the stig cli just wraps the karma test runner. The supported test styles are 'mocha', 'jasmine' and 'qunit'. However, this documentation only covers testing with mocha.

main.js

After running "stig init", your project will be initialized with a browserstig.conf.js and a main.js file. main.js is the first file that will be loaded into the browser. In this file we setup mocha to give a much longer timeout for tests. This is because functional tests usually take much longer to run than your typical unit test:

mocha.setup({timeout: 30000});

We also setup a "stig" global to be initialized before each test:

beforeEach(function ()
  stig = new BrowserStig();
});

We can now use the "stig" global in any of our tests. The following test is included in main.js by default:

The most important thing to notice is that the test uses the asynchronous features of mocha. This is why the test function accepts a "done" callback that gets passed to the stig.run function. This tells mocha to wait for the test to finish all the way before moving on to run the next one.

This test is included directly in the main.js file, but it is best to distribute your tests in multiple files. This can be easily accomplished by setting the files property in your browserstig.conf.js. For example, if you wanted to run all of the tests in all of the js files beneath the "tests" directory of your project:

...
files: [ 'tests/**/*.js' ],
...

Example Project

Here is a pre-configured sample project that you may want to use to help you get started.

Known Issues

• BrowserStig is not compatible with sites that block iframes (ie. google.com).
• BrowserStig's click function currently dose not work on anchor tags to follow the link.

Please log any other issues on github