mozrunner — Reliable start/stop/configuration of Mozilla Applications

Profile Handling and Modification

class mozrunner.Profile([default_profile[, profile[, create_new[, plugins[, preferences]]]]])

XULRunner Application Profile Handling.

default_profile is the location of the clean profile used by the application to create new profiles. If one is not provided find_default_profile() will be called and that profile used.

create_new instructs the init to create a new profile in a tmp diretory from the default_profile. Defaults to True.

profile is the location of the profile you would like to use. create_new must be set to False in order to use this.

plugins is a list of plugins to install in to the profile. You can use paths to directories containing extracted plugins or .xpi files which will b extracted and installed.

preferences is a dict of additional preferences to be set in the profile. Most Profile subclasses have a class member named “preferences”, this is copied during initialization of the instance and updated with the preferences passed to the constructor.

names

list of product names in order of priority. Not present by default, must be defined in subclass.

preferences

The default preferences dict. If another preferences dict is passed to the constructor this default will be copied and then updated.

find_default_profile()

Finds the default profile location. Uses names .

There is currently a bug in the Windows code: It’s currently hardcoded to Firefox.

create_new_profile(default_profile_location)

Creates a new profile in tmp and returns the path.

default_profile is the path to the default profile described in the class docs above.

install_plugin(plugin)

Installs a plugin in the profile.

plugin is a path to either an extracted addon or a .xpi .

set_preferences(preferences)

Takes a dict, preferences, and converts it to JavaScript set_pref() calls written to the profile’s user.js .

clean_preferences()

Cleans any preferences installed by mozunner from the profile.

clean_plugins()

Removes all plugins installed by mozrunner from the profile.

cleanup()

Triggers all cleanup operations. If a new profile was created in tmp it will remove the entire directory tree, if not it will call clean_preferences() and clean_plugins().

class mozrunner.FirefoxProfile([default_profile[, profile[, create_new[, plugins[, preferences]]]]])
Firefox specific subclass of Profile.

Process Run and Environment Handling and Discovery

class mozrunner.Runner([binary[, profile[, cmdargs[, env[, aggressively_kill[, kp_kwargs]]]]]])

Handles all running operations. Finds binary, starts and stops the process.

binary is the path to the application binary. If it is not specified find_binary() will be used to find the product binary.

profile is a Profile instance. If not specified one will be created, profile_class is used, no arguments are passed to it’s constructor.

cmdargs are additional command line arguments that will be added to the subprocess call. Defaults to []

env is a dict containing all the environment variables to be used in the subprocess call. Defaults to a copy of os.environ with {“MOZ_NO_REMOTE”:”1”} added.

aggressivel_kill is a list of additional process names that need to be killed after killing the product. Defaults to [“crashreporter”].

kp_kwargs the additional arguments sent to killablleprocess.Popen. Defaults to {}.

names

List of product names in order of priority. Not present by default, must be defined in subclass.

profile_class

The default class to use when creating a new profile when one isn’t passed to the constructor.

command

The command list for subprocess. Not usually that usable without having the instance, it’s more common to use property() for attribute. Does not need to include cmdargs sent to the constructor, those will be added later.

find_binary()

Finds the binary location. Uses names for lookup names.

There is currently a bug in the Windows code: It’s currently hardcoded to Firefox.

start()

Starts the subprocess call and sets process_handler to the returned subprocess handler.

wait()

Blocks and waits for the process to exit.

kill()

Kills the application. This call is very aggressive, it kills all process id’s that are higher than the original pid if the one of the names is in the process name.

stop()

Friendly pointer to kill()

class mozrunner.FirefoxRunner([binary[, profile[, cmdargs[, env[, aggressively_kill]]]]])
Firefox specific subclass of Runner.

Command Line Customization and Modification

class mozrunner.CLI

Command Line Interface

parser_options

dict of optparse.OptionParser option definitions. Keys are tuples with the short and long argument name definitions. Values must be a keyword argument dict:

class SubCLI(CLI):
    parser_options = copy.copy(CLI.parser_options)
    parser_options[('f', '--file')] = {"default":None, "dest":"file", "help":"Log file name."}
parser

Instace of optparse.OptionParser. Created during instance initialiation.

runner_class

Default runner class. Should be subclass of Runner. Defaults to FirefoxRunner.

profile_class

Default profile class. Should be subclass of Profile. Defaults to FirefoxProfile.

parse_and_get_runner()

Responsible for calling parser.parse_args() and setting options and args. Then responsible for calling get_profile() and get_runner() with parsed args from options and returns the runner instance. Default implementation:

def parse_and_get_runner(self):
     """Parses the command line arguments and returns a runner instance."""
     (options, args) = self.parser.parse_args()
     self.options  = options
     self.args = args
     if self.options.plugins is None:
         plugins = []
     profile = self.get_profile(default_profile=options.default_profile,
                                profile=options.profile, create_new=options.create_new,
                                plugins=plugins)
     runner = self.get_runner(binary=self.options.binary,
                              profile=profile)
     return runner
options

Options object returned from parser.parse_args(). parse_and_get_runner() is responsible for setting this attribute before calling get_profile() and get_runner().

args

Args list returned from parser.parse_args(). parse_and_get_runner() is responsible for setting this attribute before calling get_profile() and get_runner().

get_profile([default_profile[, profile[, create_new[, plugins]]]])

Takes arguments as parsed from options and returns an instance of profile_class

get_runner([binary[, profile]])

Takes arguments as parsed from options and the profile instance returned from get_profile() and returns an instance of runner_class.

start(runner)

Starts the runner and waits for Runner.wait() or KeyboardInterrupt.

run()

Calls parse_and_get_runner() and passes the returned value to start().

Examples

Firefox subclasses:

class FirefoxProfile(mozrunner.Profile):
    """Specialized Profile subclass for Firefox"""
    preferences = {'extensions.update.enabled'    : False,
                   'extensions.update.notifyUser' : False,
                   'browser.shell.checkDefaultBrowser' : False,
                   'browser.tabs.warnOnClose' : False,
                   'browser.warnOnQuit': False,
                   'browser.sessionstore.resume_from_crash': False,
                   }

    @property
    def names(self):
        if sys.platform == 'darwin':
            return ['firefox', 'minefield', 'shiretoko']
        if sys.platform == 'linux2':
            return ['firefox', 'mozilla-firefox', 'iceweasel']
        if os.name == 'nt' or sys.platform == 'cygwin':
            return ['firefox']

class FirefoxRunner(mozrunner.Runner):
    """Specialized Runner subclass for running Firefox."""
    @property
    def names(self):
        if sys.platform == 'darwin':
            return ['firefox', 'minefield', 'shiretoko']
        if sys.platform == 'linux2':
            return ['firefox', 'mozilla-firefox', 'iceweasel']
        if os.name == 'nt' or sys.platform == 'cygwin':
            return ['firefox']