zombie-navigator

Zombie Navigator

Free Software browser automation product

This is currently part of the DesktopD Project.

Note: We're working on experimental development versions now

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 limits 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+)

The addon is based on modern Firefox Addon SDK technologies on top of the newest ECMAScript 2015 standard, with some ideas from SlimerJS and GreaseMonkey. It is thus written in a future-proof way, to support coming future Firefox releases with small efforts.

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

    // Notice that many ECMAScript-6 features are already available
    // consult https://developer.mozilla.org/ for details

    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.

About

A simple Firefox automation addon FAQ

Availability

Official AMO (addon.mozilla.org) downloads (reviewed and cryptographically signed by Mozilla) at: https://addons.mozilla.org/en-US/firefox/addon/zombie-navigator/

Note that AMO downloads are bloated in size due to the bad choice of (re)compression at Mozilla. For business uses which does not require signing by Mozilla you should build Zombie Navigator from source (Git checkout, see below for instructions) to get optimal builds. You can also get reference builds from https://notabug.org/desktopd/zombie-navigator-reference-builds.

Codes

Git master is alpha (not feature-complete and subject to changes) and always experimental!

    DEVELOPMENT SCHEDULE
    --------------------

    master = 0.6.0~a1 (alpha) <=== NOW
            ||
    (possible several alpha tags)
            ||
            ||------------------------------++
    master becomes 0.7.0~a1         0.6 feature complete = branched out
            ||                              ||
            ||                      0.6.0~b1 (beta)
    (more development)                      ||
            ||                      (possible several beta releases)
            ||                      (Compatibility testing and fixes)
            ||                      (AMO beta-channel submission)
            ||                              ||
            ||                      0.6.0 (stable)
            ||                      (AMO full review, fixes goes to 0.6.1)
    (port AMO compliance updates)   (signed by Mozilla) -> tagged as AMO-0.6
            ||                              ||
                                    (At this point 0.5.x is EOL)
                                            ||
                                    (security fixes)
                                    (compatibility updates)
                                    (AMO compliance updates)
                                    (fixes for severe bugs)
                                            ||
                                    EOL is when 0.7.x is fully reviewed
                                    by Mozilla

    When will 1.0.x appear? (Super-stable, architectural changes)

• src/ The addon source code
• branding/ Branding source code (artworks)
• tools/ Building and maintenance scripts
• 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.

Intended to be fully free software as in GNU and DFSG terms. File a bug report if you find a non-free file or have questions.

What's this for?

• Run automated tests using existing Firefox profiles
• Aimed to be more compatible and less intrusive than SlimerJS
• Automate web tasks that has no API and requires a full web browser
• Anything automatic that needs a real Firefox or a real web browser
• Far simpler than Greasemonkey and requires no manual interaction
• May also be useful for an advanced Firefox user
• Any use case between SlimerJS and Greasemonkey
• No code-level compatibility with PhantomJS or CasperJS
• Pure JavaScript, no dependencies other than Firefox (unlike Selenium)
• Trivially works out of the box with (possibly) the latest Firefox (by design)

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

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

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

About License

Though this program is not a web application, we choose GNU AGPL because it provides the maximum freedom to the users even when it is embedded in a SaaS product. When a new version of the GNU AGPL is released, we will normally start to release newer version of this program under that new version of the license, unless we decide otherwise. License terms of already released versions are not affected.

We update the license (for new releases) when the Free Software Foundation publishes a new version of the license. When we release software under a forward-incompatible copyleft license like the GNU GPL (as we do most of the time) we always release it under "version x of the or any later version" even though x should be the latest version of the license at the time of release. This can help avoid a lot of headaches (and recommended by the FSF).