Wrapper for PhantomJS & SlimerJS to simplify browser tests scripting.
Note, you need to install phantomjs
or slimerjs
with this package, those are
not included as dependencies.
# for phantomjs:
npm install navit phantomjs --save
# for slimerjs:
npm install navit slimerjs --save
var Navit = require('navit'),
browser = new Navit(); // Short call: `browser = require('navit')();`
var stack = []; // You can use lazy functions to pass data between stages,
// but arrays have more compact notation.
browser
.open('http://dev.nodeca.com')
.wait(function () {
if (window.NodecaLoader && window.NodecaLoader.booted) { return true; }
})
.get.url(stack);
.click('forum-category__content:first forum-section__title-link')
.wait(function changed(data) {
if (location.url !== data[data.length - 1]) { return true; }
}, stack)
.test.exists('.forum-topiclines')
// first param `true` is equivalent to `.close()` call
.run(true, function(err) {
console.log(err || 'Succeeded');
});
Also look files in test folder.
Those are real examples how to use navit
with mocha
.
- All methods are chainable.
- Methods, marked with
+
have direct aliases without namespace. - Chain should be finished with terminator
.run([teardown,] callback)
call. - Almost everywhere
String
&Number
params can be defined as functions for lazy evaluation.
Known limitations:
Some methods like .get.evaluate()
allow to pass params to evaluated functions.
navit
uses function's .length
property, to properly detect params count,
because tailing callbacks are optional. That means, such functions must have
explicit parameters list in definition, and you must pass exactly the same
params count as defined. We decided, it's not a big price for nice API.
options (not mandatory):
inject
: Array of scripts (file paths) to inject after every page load ([ require.resolve('jquery/dist/jquery') ]
).timeout
: Page load and.wait()
timeout, default5000ms
.prefix
: url prefix for.open()
and.post()
, default empty string.engine
:'pnatnomjs'
|'slimerjs'
, default is'pnatnomjs'
. Specify engine to use. Make sure you installedphantomjs
orslimerjs
package.
engineOpts (not mandatory, camelCase):
See http://phantomjs.org/api/command-line.html and https://docs.slimerjs.org/current/configuration.html#command-line-options. You can pass any options, supported by browser engine. Option names should be in camelCase.
Navigation:
- +
.do.open(url [, options])
- options:
method
- get(default)|post|put|delete|headdata
headers
- options:
- +
.do.post(url, data[, options])
- shortcut to.open
, for convenience;method
is set topost
, anddata
is forwarded tooptions.data
. - +
.do.back()
- +
.do.forward()
- +
.do.reload()
DOM:
- +
.do.click(selector)
- click on an element matchingselector
- +
.do.type(selector, text)
- typetext
into input or contenteditable - +
.do.clear(selector)
- clear input value (supports contenteditable) - +
.do.check(selector)
- toggles checkbox or radio - +
.do.select(selector, option)
- selects anoption
in dropdown - +
.do.upload(selector, path)
- selects a file ininput[type="file"]
- +
.do.fill(selector, obj [, submit])
- not implemented yet - +
.do.scrollTo(top, left)
- executeswindow.scrollTo(top, left)
- +
.do.inject([type, ] file)
- appends a script or stylesheets from externalfile
to page,type
can be one ofjs
orcss
(default type isjs
).
Waiting:
- +
.do.wait()
- wait until page ready; can be useful afterclick
,back
andforward
actions (open
andreload
track progress for html pages automatically) - +
.do.wait(delay)
- pause fordelay
milliseconds - +
.do.wait(selector [, timeout])
- wait until selector available - +
.do.wait(fn [, params..., timeout])
- evaluate function in cycle, until returnstrue
.
All functions, passed to .get.*
, can be sync (with 1 param) or async (with 2
params). If function returns not falsy type of result (usually a Error
) or
throws exception, chain will be terminated. That can be used to create complex
test conditions.
- +
.get.title(fn)
- +
.get.url(fn)
- +
.get.count(selector, fn)
- +
.get.text(selector, fn)
- +
.get.html([selector,] fn)
- when no selector given, returns full page html. - +
.get.attribute(selector, attribute, fn)
- +
.get.value(selector, fn)
- for input/selector fields, returns field value. .get.evaluate(fnToEval [, params, fn])
- evaluate function on client with optional params. Returned result can be processed on server, if handler set..get.status(fn)
.get.body(fn)
.get.headers(fn)
- return server reply headers. Note, testing method is not "symmetric" - use.test.header(name, ...)
..get.cookies(fn)
(no pair in.test.*
)
Sugar:
- If you pass
Array
instead ofFunction
, data will be pushed into it. - If
fn
returnsError
object (or anything else not falsy), chain will be stopped with that value. - If last param (
callback
) exists, chain will be finished as with.run
method.
- +
.set.headers(obj)
- +
.set.useragent(string)
- +
.set.authentication(user, pass)
- +
.set.viewport(width, height)
- +
.set.zoom(scale)
- +
.set.cookie(obj)
- +
.set.cookie(name, value)
Tests available for the most of get.*
methods:
.test.method_name(params..., value [, message)
- If value to compare is
RegExp
, then data is converted toString
, and tested to match provided regexp. - Negative condition
.not
can be added to almost any test, before or after method name.
Additional:
- +
.test[.not].exists(selector [, message])
- +
.test[.not].visible(selector [, message])
- +
.test.evaluate(fn [params..., message])
- evaluate & die on any result buttrue
.
Special sugar:
.test(status_number [, message])
.test(body_rexexp [, message])
.test(header_name, string_or_regexp [, message])
.tab.open([url [, options]])
- create and switch to new tab. Run.do.open(url, options)
ifurl
specified.tab.count(fn)
- get tabs count (if you passArray
, value will be pushed into).tab.switch(index)
- switch to tab byindex
.tab.close([index])
- close tab byindex
or close current tab ifindex
not specified- negative
index
address tab from the tail - after all tabs closed, new one will be created automatically
- negative
.frame.enter(selector)
- switch to frame byselector
.frame.exit()
- exit to top window
.fn(function, params)
- local function execute. Function can be sync (0 params) and async (1 param)..close()
- tear down browser process. Note, browser will NOT be closed until you do it explicit via this method or.run(true, ...)
..run([teardown,] done)
- terminate sequence of commands (execute and do callback).- If
teardown
istrue
, then close the browser after the sequence finishes. It's a sugar to avoid explicit.close()
call.
- If
.screenshot([ selector|bounding_rect, type,] path)
- do screenshot.registerMethod(names, fn)
- add new method with given name(s) (names
can be string or array)..use(plugin [, params...])
- apply plugin.
navit
allows record sequence or commands to run it later with one call as
many times as you wish.
// create
.batch.create('init_page', function() {
this.
.wait(function () {
try {
return window.NodecaLoader.booted;
} catch (__) {}
return false;
});
.viewport(1600, 1200)
.inject(require.resolve('jquery/dist/jquery'))
.fn(function () {
console.log('Batch done.');
})
})
// run
.batch('init_page')
If you assign function to this property, it will be called after any .open
and .reload
definition to stack additional commands. This is experimental
feature, that can be changed.
Sometime you may wish to do global setup for all opened pages. For example:
- wait full page init, when it has dynamic scripts loader.
- inject testing scripts from remote host (when you don't like to use global option).
You can record your sequence to batch and automate it's injection after every
open
/ reload
. See example how we setup navit
in nodeca
:
// Wait for nodeca scripts load and check status
//
navit.batch.create('waitNodecaBooted', function () {
this
.wait(function () {
try {
return window.NodecaLoader.booted;
} catch (__) {}
return false;
})
.test.status(200);
});
navit.afterOpen = function () {
this.batch('waitNodecaBooted');
};
Note. .afterOpen
is called on chain definition phase, not on execution
phase. It's ~ equivalent of typing content manually in test body. That's why it
doesn't have callback to wait async operations - it's not needed.
If you assign environment variable DEBUG
to navit
, you will see debug message
for every action.
Output example for DEBUG=navit mocha
:
...
navit do.open('http://localhost:17345/test/fixtures/do/type.html') +25ms
navit do.type('#type-test') +20ms
navit test.evaluate() +9ms
navit do.type('#contenteditable-test') +2ms
navit test.evaluate() +9ms
✓ type (64ms)
...
Here are links to other similar libraries and comments why we did this one. Note that comments are given according to our requirements. Your ones can be different. May be you need more to scrape data from real sites instead of interface testing and so on. Select the best package for you needs:
- CasperJS
- Runs standalone. You will not be able to control server and browser from single script (load fixtures to db, prior to open page).
- Tests could be more compact, if CasperJS allows curried style.
- Zombie.js
- Uses jsdom. Nice idea, but jsdom emulation is a bit limited for complex things. We prefer real browser engines like PhantomJS and SlimerJS.
- Nightmare
- That was the nearest to our needs, and we used it before.
- It has poor errors control if error happpens in the middle of batch. For example, if you wait for selector, it's difficult to check do you finished with succes or by timeout.
- Too few built-in assertions.
- Not actively developped (see tracker - some problems caused by buggy bridge to PhantomJS are not fixed for a long time).
- Horseman
- Has sync api, that can be convenient for scraping.
- Sync api limits you with getting multiple data from browser to server - getter should be the single, always the last. You can workaround this limitation, but that will increase amount of code to write.