zombie-navigator

Zombie Navigator

Free Software browser automation product

This is currently part of the DesktopD Project.

Good solutions to web automation have always been desired. In Mozilla world, SlimerJS (similar to PhantomJS) exists but it is strictly not Firefox (but a different XUL application) and that limit its possibilities. Selenium doesn't catch up with latest Firefox and it also requires a lot of codes outside Firefox.

This addon tries to improve this situation. It is a pure-Firefox web automation product that is Free Software. When Firefox works, this addon should also work. So it can, being very lightweight, automate most to all Firefox-related use cases. There are many many Firefox-based or Firefox-embedded products in the world. We can now use this addon to run testsuites on these products without modification. In theory we can, and if not, it's a bug. (Though this is Firefox 38+)

With the addon you can automate Firefox (or derivatives) with a single script file you like. We call such a script a "Zombie script" and Zombie scripts use the "Zombie API" to do their jobs. The Zombie API is documented inside the addon but this is how it looks like:

'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);
  }
});

Command line (GNU/Linux):

$ ZOMBIE_NAVIGATOR_SCRIPT_PATH=<path_to_script> firefox

Command line (Apple OS/X):

$ ZOMBIE_NAVIGATOR_SCRIPT_PATH=<path_to_script> /Application/Firefox.app/Contents/MacOS/firefox

For pseudo-headlessness, Xvfb is supported. Use like this:

$ ZOMBIE_NAVIGATOR_SCRIPT_PATH=<path_to_script> xvfb-run firefox

A script can now most of times shut down Firefox if the user (if any) does not open any tabs. This feature is getting improved, but is incomplete. So please expect windows not closed properly in some cases.

Though this addon is simple, it is similar to SlimerJS. But this is a Firefox addon, like Greasemonkey, and not a standalone application. So it can easily be used to run automated tests with existing Firefox profiles (with your favorite addons installed). That makes it more useful inside an organization.

This addon is designed to change as little of Firefox as possible while it tries to make clear what the script is doing.

This addon is not a server-side application, but for maximum software freedom in case embedded in a SaaS product, we license the addon under the GNU AGPL.

About

A simple Firefox automation addon

• src/ The addon source code
• branding/ Branding source code (artworks)
• jsdoc/ JSDoc-based API documentation source code (experimental)
• run.sh Run the addon off the source tree (requires non-release non-beta Firefox due to signing requirement)
• LICENSE The GNU Affero General Public License, version 3

Firefox (or equivalent) 38+ is required.

Build requirements

• NodeJS and NPM
• Built using jpm (install with $ make npm)
• JSDoc for API documentation (install with $ make npm)
• (Optional) AdvanceCOMP (advzip utility) for a smaller file size ($ apt-get install advancecomp on debian-based systems)
• (Optional) Perl 5 (used for CSS minification)
• Build scripts only support Unix-like systems (Note that the shell scripts here use a POSIX /bin/sh, which is not necessarily GNU bash.)

Building

• Prepare the up-to-date dependencies: $ make npm (note: huge dependencies)
• (Optional) Fetch and build zopflipng from Google: $ make zopflipng (please run if you don't have one installed)
• Build the addon: $ make
• (Optional) Rebuild the documentation with JSDoc: $ make docs
• (Optional) Create a source tarball: $ make archive
• (Optional) Rebuild the icons: $ make icon

TODO

• Make sure the API is always reliable
• Run script from the about:addon page (simple-script module in the SDK)
• "Stop all" button in the about:addon page??
• Per-script user controls??
• Confirm that the addon should work properly in "partial restart" cases -> does nothing?
• Fade out JSDoc
• Reset preferences on uninstall (so that the next installation will be "fresh")?
• Use NodeJS for build scripts? (but remember we hate npm and semver.org)

Branding

We named this program "Zombie Navigator" because it effectively turns Firefox into an automated "zombie" web browser. "Zombie scripts", which run inside a secure sandbox navigate Firefox!

The icon says "Web Browser" in Arabic. Just that. Maybe too simple. But we do not invest much in visual design.

Firefox is a registered trademark of the Mozilla Foundation. The term "Firefox" in this product, however, may also mean rebranded products derived from the official Firefox.

Versioning

• https://github.com/mojombo/semver/issues/145
• We use ~ for prereleases (compatible with AMO)

License

Copyright © 2015 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 http://www.gnu.org/licenses/.

The GNU Affero General Public License (GNU AGPL for short) is included under the file name 'LICENSE'