Serial Kiwi
A PhantomJS wrapper for easy webpage automation.
- Free software: MIT License
- History: HISTORY.md
- How to contribute: CONTRIBUTING.md
Install
Install via NPM
npm install serialkiwi
Usage
-
Require SerialKiwi:
var sk = require('serialkiwi');
-
Define the PhamtomJS tasks serially:
// Open a webpage sk.open('http://yahoo.com'); // Take a screenshot after the webpage has loaded sk.screenshot('yahoo.png'); // Open a different webpage and execute code in its context sk.evaluate('http://google.com', function() { '...' // Handle exceptions via onerror callback }).onerror(function(err) { console.log(err); }); // Execute a new block of code on the last opened webpage sk.evaluate(null, function() { '...' return 'X'; // Retrieve the returned values from the webpage's context }).then(function(result) { console.log(X); // i.e. 'X' // Chain an error callback }).onerror(function(err) { console.log(err); }); // Do something in PhantomJS' context after all previous steps sk.then(function() { '...' });
-
Run the tasks:
sk.run();
SerialKiwi API
-
open: function (url)
Opens a webpage and will not defer execution to the next task until onLoadFinished() is invoked.
sk.open('yahoo.com');
Current version does not return anything after calling
open()
. Future versions will return a promise similar toevaluate()
. -
evaluate: function (url, onload, args)
Evaluates Javascript code in the context of a webpage. If URL passed is
null
, then the last opened webpage is used.sk.evaluate('http://google.com', function() { '...' });
Arguments to the evaluate function can be passed via the
args
parameter.sk.evaluate('http://google.com', function(x) { console.log(x); // "1234" }, '1234');
If no URL is given,
evaluate()
will be executed in the current webpage's context (i.e. in the same webpage from the last call toopen()
orevaluate()
.sk.evaluate(null, function() { '...' });
The return value is a promise that has callbacks
then()
andonerror()
.then()
is always called and its parameter is populated with whatever the webpage's context returns.onerror()
is only called if an error is thrown within the webpage's context.sk.evaluate('http://google.com', function() { '...' }).then(function(res) { // Always called, res can be undefined }).onerror(function(err) { // Called only when an error is thrown, err contains the error message but no stack trace });
-
then: function (callback, args)
Executes a block of code serially in PhantomJS' context. This could be used, for example, to evaluate results from multiple
evaluate()
's.var resultStore = []; // result accumulator sk.evaluate('http://yahoo.com', function() { '...' // get a result from page 1 }).then(function(res) { resultStore.push(res); }); sk.evaluate('http://google.com', function() { '...' // get a result from page 2 }).then(function(res) { resultStore.push(res); }); sk.then(function(res) { console.log(res.length); // Do something with resultStore }, resultStore);
-
screenshot: function(outfile)
Takes a screenshot of the current webpage's state and saves it to
outfile
.sk.open('http://google.com'); sk.screenshot('http://google.png');
-
sleep: function(millis)
Sleeps for
millis
milliseconds.sk.sleep(1000); // wait for 1 second prior to executing the next task
-
waitFor: function (userFunction, timeoutMillis, intervalMillis)
Awaits until the provided
userFunction
returns value that evaluates astrue
. This function will executeuserFunction()
everyintervalMillis
milliseconds; if aftertimeoutMillis
milliseconds the function has not evaluated astrue
, it calls theonerror()
handler. Otherwise, it will call thethen()
handler after success and pass the result ofuserFunction()
as parameter (which must be a truthy value).var semaphore = 'red'; sk.then(function() { setTimeout(function() { semaphore = 'green'; }, 1000); }); sk.waitFor(function() { return semaphore === 'green'; }); ...
-
waitForElement: function (elemQuery, timeoutMillis, intervalMillis)
Awaits until the provided element query returns at least one element.
elemQuery
is simply passed as a parameter towindow.document.querySelector()
. This function will execute the query selector everyintervalMillis
milliseconds; if aftertimeoutMillis
milliseconds the query selector does not return any elements, it calls theonerror()
handler. Otherwise, it will call thethen()
handler after success and pass the result ofwindow.document.querySelector()
as parameter (which must be a truthy value).sk.open('yahoo.com'); sk.waitForElement('#Main'); sk.evaluate(null, function() { '...' });
-
debug: function(flag)
Sets debugging mode to
flag
.sk.debug(true); // print debug statements to console
-
run: function (callback, timeoutMillis)
Executes all the defined tasks. If
callback
is not provided, it executesphantom.exit()
after all tasks have completed. IftimeoutMillis
is provided, PhamtomJS will forcefully exit after the given number of milliseconds regardless of the task execution state.sk.run(phantom.exit, 60000); // Run all tasks or exit after a minute, whichever happens first