A small utility library for testing client-side code in Node.js environment. Simulate the browser in your terminal.
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.
npm install atomus
All you have to do is to require the module, call the
var htmlStr = '<body><h1>Atomus</h1></body>';var atomus = ;var browser =;
element.dispatchEvent. In practice we may interact with the page as we are in a real browser.
browser.ready([callback])- call this method when you are ready with configuring your browser. The callback receives
browser.html([string])- the initial HTML markup of the page
ready method is called we have a few other methods and objects available.
browser.window- the usual Window object
browser.clicked([jQuery object or DOM element])- fires
browser.changed([jQuery object or DOM element])- fires
browser.focused([jQuery object or DOM element])- fires
browser.blurred([jQuery object or DOM element])- fires
browser.keypressed([jQuery object or DOM element], [keyCode])- fires
keypressevent with particular keyCode.
browser.selected([jQuery object or DOM element])- fires
clickevent. 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 DOM
browser.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 a
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 mocks
browser.triggerEvent([element], [eventType], [keyCode]) - triggers a DOM event on particular element with particularkeyCode`
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.
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: 200responseText: JSONurl: '/api/method/action'method: 'POST'response:status: 200responseText: JSON;var atomus = ;var b =external__dirname + '/data/ajaxwrapper.js';
var b =;
- 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
.valueproperty you need to dispatch a
changeevent. 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.Angularand not just
- 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.logcalls so you receive all the logs into the terminal
- The library supports
localStorage. However, it is not part of jsdom. It's a polyfill.