Zombie Navigator: API Documentation v0.6.0~a2

Zombie Navigator API (ZAPI): Secure Firefox automation API. Firefox (or equivalent) 38+ is required. Documentation for version 0.6.0 Note: '*' here means 'any type'

License

Copyright © 2016 Zombie Navigator Developers

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see https://www.gnu.org/licenses/.

Usage

Command-line usage example: $ ZOMBIE_NAVIGATOR_SCRIPT_PATH=/tmp/script.js firefox /tmp/script.js: 'use strict'; const {delay, run} = require('zombie/async'); const {console} = require('zombie/zombie'); run(function* () { const {openWindow, openPrivateWindow} = require('zombie/webbrowser'); try { let window1 = yield openWindow('about:'); console.log(window1.uri); yield delay(5); // sleep for 5 seconds let promise = window1.runScript(uri => { location.href = uri; return 42; }, 'about:buildconfig'); yield window1.waitForReload(); console.log((yield promise), window1.uri); yield delay(10.5); // sleep for 10.5 seconds yield window1.close(); console.log('closed'); } catch (e) { console.error('Error:', e); } }) .catch(function (e) { // uncaught exceptions });

Modules

Module: zombie/async

Asynchronous helper utilities

Usage

const {run} = require('zombie/async');
run(function* () {
	try {
		let result = yield new Promise(...);
	} catch (e) {
		// rejected
	}
	throw new Error();
})
.then(function (result) {
	// generator is finished
})
.catch(function (e) {
	// an error in generator
});

Properties

Methods

delay (number s) : {Promise → boolean}
Asynchronous sleep using Promise Parameters: number s : The number of seconds to sleep for
run (function genFunction) : {Promise → *}
Tun a generator as a coroutine using Promise function genFunction: Generator function (coroutine) to run const {run} = require('zombie/async'); run(function* () { try { let result = yield new Promise(...); } catch (e) { // rejected } throw new Error(); }) .then(function (result) { // generator is finished }) .catch(function (e) { // an error in generator });

Module: zombie/webbrowser

Open and control Web-browser windows

Properties

Methods

closeAll () : {Promise → boolean}
Close all windows opened by the Zombie script. If there are no other windows, the browser should quit (TODO: not on OS/X, probably)
openPrivateWindow (string uri) : {Promise → ZombieWindow}
Open a private window (tab)
openWindow (string uri) : {Promise → ZombieWindow}
Open a window (tab)

Interface: zombie/webbrowser~ZombieWindow

Usage
require('zombie/webbrowser').openPrivateWindow('about:')
.then(window => {
	console.log(window.uri);
})
.catch(e => {
	console.exception(e); // failed
});
Properties
isPrivate :boolean (readonly)
Whether this window is private (Private Browsing)
uri :string (readonly before 0.4.0)
The URI of the window // writable since 0.4.0 window.uri = 'about:'; window.waitForReload() .then(...)
Methods
close () : {Promise → boolean}
Close the window
reload () : {Promise → boolean}
Reload this window
runScript (function callback [, ... * args]) : {Promise → *}
Run a script inside this window (tab) Parameters: {function} callback : The script to run {*} ... args : Passed to the callback (optional) Returns: Resolves to the result of the callback let promise = w.runScript(function (arg1, arg2) { console.log(document.title); return 'result'; }, 'arg1', 'arg2');
screenshot ([boolean windowSized = false]) : {Promise → string}
Take a screenshot of the page into a data: URI Available since 0.6.0 Parameter: boolean windowSized : Whether the screenshot is limited to the browser window boader (optional) w.screenshot().then(dataURI => { w.uri = dataURI; });
waitForReload () : {Promise → boolean}
Wait until the tab is reloaded

Module: zombie/zombie

Miscellaneous utilities

Properties

console :{ZombieConsole} (readonly)
Console logging interface
env :object (readonly)
Access environment variables (use getEnvName() to get the real (mapped) name of a variable) Since version 0.4.0 const {env, getEnvName} = require('zombie/zombie'); env.my_variable; // may be empty ('') getEnvName('my_variable'); // real variable name
zombie :{ZombieInfo} (readonly)
Query Zombie features See interface ZombieInfo

Methods

getEnvName (string name) : string
Get the real name of an environment variable Available since version 0.4.0

Interface: zombie/zombie~ZombieConsole

Console API Note that some console output may be suppressed due to the settings

Usage
const {console} = require('zombie/zombie');
console.info('Aloha');
Properties
Methods
debug (... * message)
Log a debugging message
error (... * message)
Log an error message
exception (... * message)
Log an exception
info (... * message)
Log an informational message
log (... * message)
The same as debug()
notice (... * message)
Log a notification message Since: version 0.6.0
warn (... * message)
Log a warning

Interface: zombie/zombie~ZombieInfo

Query for Zombie Navigator features and information

Usage
const {zombie} = require('zombie/zombie');
zombie.showNotification('Version: ' + zombie.version);
Properties
applicationName :string (readonly)
The name of the application (browser)
applicationVersion :string (readonly)
The version of the application
licenseURI :string (readonly)
The URI of the addon's license text: only valid inside the browser Since: version 0.5.0
productName :string (readonly)
The name of this addon
version :string (readonly)
The version of this addon
Methods
print (... string data) : number
Print one or more strings to STDOUT Returns: the number of bytes written
showNotification (string text)
Show a notification to the user