feat: You can now use web-ext programatically, e.g. webExt.cmd.run()

[kumar303]

Fixes #683

This only supports minimal programmatic use. You can execute raw functions without any argument validation, like:

import webExt from 'web-ext';

webExt.cmd.run({shouldExitProgram: false, firefox: '...', sourceDir: '...'})
  .then((extensionRunner) => {
    console.log(extensionRunner);
    // extensionRunner.reloadAllExtensions();
    // extensionRunner.exit();
  });

One would have to set up verbose logging manually:

webExt.util.logger.consoleStream.makeVerbose();
webExt.cmd.run({shouldExitProgram: false, firefox: '...', sourceDir: '...'});

You can also disable the use of standard input:

webExt.cmd.run({shouldExitProgram: false, noInput: true});

Here is an example of disabling manifest validation if you want to work with an add-on that's not a WebExtension:

webExt.cmd.run({shouldExitProgram: false}, {
  getValidatedManifest: () => ({
    name: 'auto-generated-name',
    version: '1.0.0',
  }),
});

[coveralls]

Coverage remained the same at 100.0% when pulling fbba629 on kumar303:js-api-iss683 into e48ac75 on mozilla:master.

[coveralls]

Coverage remained the same at 100.0% when pulling 5200ea8 on kumar303:js-api-iss683 into e48ac75 on mozilla:master.

[chrmod]

not sure why the logger is needed. should there be any doc for it?

[kumar303]

not sure why the logger is needed.

I was thinking that the caller may want to have some control over the log output. The could also replace webExt.util.logger.consoleStream.write with a no-op if desired.

should there be any doc for it?

Yeah, definitely. The way we do it is once the issue lands and web-ext gets deployed with the change, we document it on MDN.

[kumar303]

... although, hmm, maybe the README should have some docs since this usage is more developer focused.

[chrmod]

if there would be a way to silence/capture the logs through logger object, it is definitely very useful for embedding purposes.

Dev oriented docs could be published at readthedocs, what do you think?

[kumar303]

Dev oriented docs could be published at readthedocs, what do you think?

I don't want to maintain and manage another service. I think we can try it in our current documentation and see how hard it is.

[rpl]

@kumar303 👍 Nice! This is pretty neat!

The change seems ok to me, but I'm wondering if we should make some tweak to the defaultReloadStrategy, mostly to make the caller of the API able to disable or customize the "interactive" behavior (e.g. reading from stdin when used as a library doesn't seem a great idea, it is probably something that the caller may want to easily disable and maybe manage with an API object which allow it to know when a change has been detected, trigger the addon reload and exit the runner).

What do you think?

[kumar303]

Thanks @rpl , good idea about disabling input. Could you take another look? I added noInput as a global param to all commands but I didn't hook it up in yargs yet. We could do that in a separate patch so that we have a global --no-input option.

[coveralls]

Coverage remained the same at 100.0% when pulling df599b7 on kumar303:js-api-iss683 into e48ac75 on mozilla:master.

[rpl]

@kumar303 👍 looks great

Let's file the following as followups:

• expose noInput through yargs (maybe also aliased to '--no-interactive'?)
• return a useful API object from cmd.run (e.g. an object which provides a reload() method which reloads the extension which rejects if the reload fails, with the same error logged in the console, and an exit() method which exits the managed Firefox instance and the watcher)

[kumar303]

return a useful API object from cmd.run

It's currently returning extensionRunner which already does what you're proposing, right? I see methods like reloadAllExtensions() and exit().

[kumar303]

Feature request for --no-input: #1030

[rpl]

It's currently returning extensionRunner which already does what you're proposing, right? I see methods like reloadAllExtensions() and exit().

currently we are returning firefoxApp, which was what we used to return before the refactoring,
but I agree that returning the extensionRunner would do it.

It seems to be what #1027 is aiming to, though, and so there is no need to file another issue for it.