Écrire des commandes GCLI

La documentation qui vient avec GCLI a une section sur l'écriture des commandes. L'article qui suit décrit le support GCLI fourni dans Firefox.

Types

Par défaut, Firefox supporte les types suivants :

Les types GCLI de base : string, number, boolean, date,
setting, settingValue: c'est à dire les préférences (settingValue est une string, un nombre, ou un booléen en fonction du type d'option)
node: Un noeud unique référencé par une expression CSS
resource: Fichier CSS ou JavaScript

Nous travaillons actuellement sur les types de fichier, mais ils sont actuellement incomplets. Pour l'instant, vous devez utiliser string.

Documentation plus poussée

Le projet GCLI contient plusieurs pages de documentation pertinentes :

Acceder à Firefox

Lorsqu'une commande est exécutée, deux paramètres lui sont passés args et context. ceux-ci sont expliqués dans la documentation GCLI. Firefox fournit un environnement qui contient les éléments suivants :

chromeDocument, chromeWindow: Autorise les accès à l'environnement du navigateur.
document,window: Autorise l'accès à la page web courante.
target: Auorise l'accès à l'objet cible de la page courante.

Par exemple :

gcli.addItems([{
  name: 'closebrowserwindow',
  exec: function(args, context) {
    context.environment.chromeWindow.close();
  }
}]);

Ou :

gcli.addItems([{
  name: 'countdivs',
  exec: function(args, context) {
    return context.environment.document.querySelectorAll('div').length;
  }
}]);

Internationalisation / Localisation

La façon qu'utilise GCLI pour faire de la localisation (pour le web) ne fonctionne pas avec les commandes qui sont intégrées à Firefox.

Pour ajouter une commande qui ne sera utilisée que dans Firefox, il s'agit de la bonne procédure. Les chaines de caractères doivent être stockées dans browser/locales/en-US/chrome/browser/devtools/gclicommands.properties,
Et il faut y accéder en utilisant gcli.lookup(...) ou gcli.lookupFormat().

Pour des exemples de commandes existantes, vous pouvez regarder dans browser/devtools/webconsole/GcliCommands.jsm, qui contient la majorité des commandes GCLI. Lors de l'ajout d'un nombre conséquent de nouvelles commandes, il est conseillé de penser à faire une nouvelle JSM.

Vos commandes devraient ressembler à ceci :

gcli.addItems([{
  name: 'greet',
  description: gcli.lookup("greetDesc")
  ...
}]);

Tests unitaires

La ligne de commande est fournie avec un framework qui facilité l'écriture de tests.

Les méthodes test() ressemblent à ceci :

function test() {
  DeveloperToolbarTest.test(TEST_URI, function(browser, tab) {
    testThis(browser, tab);
    testThat(browser, tab);
    finish();
  });
}

Il a y a 2 fonctions d'aide au test :

checkInputStatus() qui vérifie si la ligne de commande peut comprendre correctement les inputs et sait ce qui est alloué et désaloué.
exec() qui vérifie si la commande à l'opération correcte lors de l'exécution.

checkInputStatus

Tout les appels à checkInputStatus() nécéssitent une chaine de caractère du need an input string in the typed property, and optionally a cursor property to specify where the cursor is when the checks are made. It will be common to leave this out, in which case the cursor is assumed to be at the end of the command line.

DeveloperToolbarTest.checkInputStatus({
  typed:  "echo hi",
  // checks go here
});

There are 3 states that are important to the command line:

VALID: Obvious - this is ok and ready to go
INCOMPLETE: This is not valid, but it's possible to make it valid just continuing to add characters
ERROR: This is wrong, and no amount of adding characters will help

The distinction between INCOMPLETE and ERROR is obvious when you consider the command 'cat README.TX' - assuming that the file to be displayed is README.TXT, as it stands it's not right, but we shoudn't be marking it as an error either.

These states apply to individual characters (and decide the underline state) and to the command line as a whole, which is generally the worst of these statuses, plus other checks.

There are 5 checks that can be made by checkInputStatus():

status: One of the strings "VALID", "ERROR", "INCOMPLETE"
emptyParameters: And array containing the parameters that still need typing
directTabText: What will be added to the command line when TAB is pressed if the completion is a simple extension of what is there already
arrowTabText: As above for when the completion text isn't an extension of what's there - e.g. for fuzzy matching
markup: One char for char on the input being the first letter of the status of that char. e.g. "VVVIIIEEE"

For example:

DeveloperToolbarTest.checkInputStatus({
  typed:  "edit c",
  markup: "VVVVVI",
  status: "ERROR",
  directTabText: "ss#style2",
  emptyParameters: [ " [line]" ],
});

exec

The exec() test is similar to checkInputStatus() except that it's more about checking the output and effect of running the command. The typed property is the same, however the checks are different:

args: an object that matches the args object passed to exec
outputMatch: A RegExp or Array of Regexps which should all match the textual content of the output
blankOutput: true if the command should produce no output
completed: false if the command should execute asynchronously

First example:

DeveloperToolbarTest.exec({
  typed: "console close",
  args: {},
  blankOutput: true,
});

ok(!(hud.hudId in imported.HUDService.hudReferences), "console closed");

Second Example:

DeveloperToolbarTest.exec({
  typed: "pref set devtools.editor.tabsize 9",
  args: {
    setting: imports.settings.getSetting("devtools.editor.tabsize"),
    value: 9
  },
  completed: true,
  outputMatch: [ /void your warranty/, /I promise/ ],
});

More Info

Some additional links which could be useful:

The test harness itself, which could be useful to see how the tests are run
Examples of existing tests