É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

Un travail sur les types de fichier est en cours, 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',
  runAt: 'client',
  exec: function(args, context) {
    context.environment.chromeWindow.close();
  }
}]);

Ou :

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

Note: Afin d'accéder à l'environnement, chrome (context.environment.chromeWindow); il est nécessaire de préciser runAt: 'client' (pour un exemple, voir : paintflashing.js dans les commandes par défaut).

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ésalloué.
  • exec() qui vérifie si la commande à l'opération correcte lors de l'exécution.

checkInputStatus

Tous les appels à checkInputStatus() nécessitent une chaine de caractère de propriété typed , et optionelement une propriété cursor pour spécifier ou le curseur est lorsque les vérifications sont faites. Il est courant de ne pas le préciser. Dans ce cas le curseur sera considéré comme étant à la fin de la ligne de commande.

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

Il y a 3 états qui sont importants pour la ligne de commande :

  • VALID: Évident - le statut est valide et prêt à pour continuer.
  • INCOMPLETE: Non valide, mais il est possible de le rendre valide en continuant d'ajouter des caractères.
  • ERROR: Non valide. Et aucun ajout de caractères n'y changera quoi que ce soit.

La distinction entre INCOMPLETE et ERROR est évidente lorsque l'on considère la commande 'cat README.TX' - en assumant que le fichier à afficher est bien README.TXT, pour l'instant la commande n'est pas valide. Mais il ne faut pas la considérer comme une erreur non plus.

Ces états s'appliquent aux caractères individuels (et sont la cause de l'état général) mais aussi à la commande tout entière. Ce qui est généralement le pire de ces statuts, plus d'autres vérifications.

Il y a 5 vérifications qui peuvent être faites par checkInputStatus():

  • statuts: Une des chaines "VALID", "ERROR", "INCOMPLETE"
  • emptyParameters: Un tableau contenant les paramètres qui ont encore besoin d’être écrits.
  • directTabText: Ce qui sera ajouté à la ligne de commande lorsque TAB est pressée si la complétion est une simple extension de ce qui est déjà présent.
  • arrowTabText: Comme ci-dessus, cette vérification est pour quand le texte de complétion n'est pas une extension de ce qui est écrit
  • markup: Un caractère par caractère de la commande pour indiquer l'état de ce caractère. Par exemple: "VVVIIIEEE"

Par exemple :

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

exec

Le test exec() est similaire au test test checkInputStatus() sauf qu'il sert plus à vérifier le résultat et l'effet d'exécuter la commande. La propriété typed est la même, mais les vérifications sont différents :

  • args: un bojet qui correspond aux arguments de l'objet passé à exec
  • outputMatch: Une RegExp ou un tableau de Regexps qui devrait contenir toutes les correspondances textuelles du résultat.
  • blankOutput: true si la commande ne produit aucun résultat (textuel=.
  • completed: false si la commande doit s'exécuter de manière asycrhonne.

Premier exemple:

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

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

Deuxième exemple:

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/ ],
});

Plus d'informations

Quelques liens pouvant être utiles :

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : maximelore
 Dernière mise à jour par : maximelore,