A small utility library for testing client-side code in Node.js environment. Simulate the browser in your terminal.
The problem
We all know about Selenium and PhantomJS. They work well for testing client-side code. We may visit a page, fill forms, click buttons etc. However, it gets complex if we want to test only part of our application. We have to create a page that contains only the needed pieces. This definitely does not scale.
Atomus is helpful during unit or functional testing. That's where the name came from. It works good with the atoms of your application. You simply include your framework and the module that needs testing. Then create an instance and start playing with the DOM and the module's API.
Installation
npm install atomus
Simple usage
All you have to do is to require the module, call the ready
method:
var htmlStr = '<body><h1>Atomus</h1></body>';var atomus = ;var browser = ;
The window
that is passed to our callback is the good old Window object that we have in every browser. Thankfully to jsdom we have a JavaScript implementation of the WHATWG DOM and HTML standards. So we may call window.document.querySelector
or element.dispatchEvent
. In practice we may interact with the page as we are in a real browser.
API
browser.ready([callback])
- call this method when you are ready with configuring your browser. The callback receiveserrors
andwindow
object.browser.external([filepath])
- add an absolute path to JavaScript file that you want to be injected into the page. This may be a framework or custom bundled JavaScript for example.browser.html([string])
- the initial HTML markup of the pagebrowser.injectJS([string])
- injects JavaScript just before the closing of<head>
tag
Once the ready
method is called we have a few other methods and objects available.
browser.$
- jQuerybrowser.window
- the usual Window objectbrowser.clicked([jQuery object or DOM element])
- firesclick
event.browser.changed([jQuery object or DOM element])
- fireschange
eventbrowser.focused([jQuery object or DOM element])
- firesfocus
eventbrowser.blurred([jQuery object or DOM element])
- firesblur
eventbrowser.keypressed([jQuery object or DOM element], [keyCode])
- fireskeypress
event with particular keyCode.browser.selected([jQuery object or DOM element])
- firesclick
event. Use this while you operate with radio or checkboxes.browser.waitUntil([element's selector], [function])
- it calls the function once the element matching the elector exists in the DOMbrowser.changeValueOf([jQuery object or DOM element], [value])
- use this method to change the value of text input, textarea or dropdown/select element. It changes the value and dispatches achange
event.browser.addXHRMock([object or array])
- by default Atomus performs real HTTP requests. That's a way to mock these requests and provide your own response. Checkout the example section below.browser.clearXHRMocks()
- clearing the already added XHR mocksbrowser.triggerEvent([element], [eventType], [keyCode]) - triggers a DOM event on particular element with particular
keyCode`
JSDom has some problems with radio and checkboxes selecting. That's why we introduced API methods for triggering events. For sure you may use $('#link').trigger('click')
but that's not working properly in some cases. So, we recommend using browser
API for dispatching DOM events.
Example
Clicking a link on the page.
var atomus = ; external__dirname + '/libs/myframework.min.js' ;
An alternative syntax for setting the initial HTML on the page and the external resources is:
var atomus = ;var b = ;
Mocking HTTP requests
var mockups = url: '/api/method/action' response: status: 200 responseText: JSON url: '/api/method/action' method: 'POST' response: status: 200 responseText: JSON ; var atomus = ;var b = external__dirname + '/data/ajaxwrapper.js';
Injecting JavaScript into the head of the document
var b = ;
Tests
npm install
npm test
Checkout the test
folder. There are tests that run Atomus against AngularJS and Ractive.js frameworks.
Notes
- Have in mind that often you have to take care about the events' triggering. For example if you change the value of an input field by setting
.value
property you need to dispatch achange
event. Otherwise you will not get the listeners called. - The global scope is accessible via the window object. So if you import Angular, for example, on the page you need to reference it through
window.Angular
and not justAngular
. - Atomus is based on JSDOM which is not simulating everything. You may not be able to use the History API for example.
- Atomus successfully patches the
console.log
calls so you receive all the logs into the terminal - The library supports
localStorage
. However, it is not part of jsdom. It's a polyfill.