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

1. Require SerialKiwi:

   var sk = require('serialkiwi');

2. 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() {
   	'...'
   });

3. 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 to evaluate().

• 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 to open() or evaluate().

   sk.evaluate(null, function() {
   	'...'
   });

  The return value is a promise that has callbacks then() and onerror(). 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 as true. This function will execute userFunction() every intervalMillis milliseconds; if after timeoutMillis milliseconds the function has not evaluated as true, it calls the onerror() handler. Otherwise, it will call the then() handler after success and pass the result of userFunction() 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 to window.document.querySelector(). This function will execute the query selector every intervalMillis milliseconds; if after timeoutMillis milliseconds the query selector does not return any elements, it calls the onerror() handler. Otherwise, it will call the then() handler after success and pass the result of window.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 executes phantom.exit() after all tasks have completed. If timeoutMillis 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