serialkiwi v0.1.9

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.
  
  	```javascript
  	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.
  
  	```javascript
  	sk.evaluate('http://google.com', function() {
  		'...'
  	});
  	```
  
  	Arguments to the evaluate function can be passed via the `args` parameter.
  
  	```javascript
  	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()`.
  
  	```javascript
  	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.
  
  	```javascript
  	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.
  
  	```javascript
  	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`.
  
  	```javascript
  	sk.open('http://google.com');
  	sk.screenshot('http://google.png');
  	```

• sleep: function(millis)

  	Sleeps for `millis` milliseconds.
  
  	```javascript
  	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).
  
  	```javascript
  	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).
  
  	```javascript
  	sk.open('yahoo.com');
  	sk.waitForElement('#Main');
  	sk.evaluate(null, function() {
  		'...'
  	});
  	```

• debug: function(flag)

  	Sets debugging mode to `flag`.
  
  	```javascript
  	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.
  
  	```javascript
  	sk.run(phantom.exit, 60000); // Run all tasks or exit after a minute, whichever happens first
  	```