search

cnumr / GreenIT-Analysis-cli

Wrapper de l'extension GreenIT Analysis
GNU Affero General Public License v3.0
45 stars 18 forks source link

readme

English version

GreenIT-Analysis-cli

Cette application est basée sur l'extension Chrome GreenIT-Analysis (https://github.com/cnumr/GreenIT-Analysis).

Sommaire

Principe de l'outil

Cet outil simule l'exécution de l'extension sur les pages spécifiées ouvertes dans Chromium en passant par Puppeteer pour récuperer les résultats.

Le système de cache est désactivé pour fiabiliser l'analyse d'une page.

Selon les pages à analyser, il peut être nécessaire de mettre en place une condition afin d'attendre la fin du chargement de la page (voir le paragraphe Construction du fichier d'entrée de l'analyse).

Pour commencer

Pour utiliser l'outil, il faut au préalable vérifier les prérequis et réaliser les étapes d'installation.

Pour cela, deux manières différentes de pouvoir l'utiliser :

Node.js

Prérequis

Installation

  1. Récupérer le code source : 
    git clone https://github.com/cnumr/GreenIT-Analysis-cli.git
  2. Se positionner dans le répertoire GreenIT-Analysis-cli : 
    cd GreenIT-Analysis-cli
  3. Installer les packages NPM : 
    npm install
  4. Créer le lien symbolique pour faciliter l'usage de l'outil : 
    npm link

Docker

Prérequis

Installation

  1. Créer le dossier /<path>/input qui vous permettra de mettre à disposition le fichier <url_input_file> au conteneur : 
    mkdir -p /<path>/input
  2. Autoriser tous les utilisateurs à lire dans le dossier /<path>/input : 
    chmod 755 /<path>/input
  3. Créer le dossier /<path>/output qui vous permettra de récupérer les rapports générés par le conteneur : 
    mkdir -p /<path>/output
  4. Autoriser tous les utilisateurs à écrire dans le dossier /<path>/output : 
    chmod 777 /<path>/output
  5. Récupérer le code source : 
    git clone https://github.com/cnumr/GreenIT-Analysis-cli.git
  6. Se positionner dans le répertoire GreenIT-Analysis-cli : 
    cd GreenIT-Analysis-cli
  7. Construire l'image Docker : 
    docker build -t greenit-analysis-cli .

    ⚠️ Si vous êtes sur MacOS, vous devez lancer la commande avec l'option --platform=linux/amd64 :

    docker build --platform=linux/amd64 -t greenit-analysis-cli .

Configurer un proxy

Si vous avez besoin de configurer un proxy, il faut :

  1. Modifier le Dockerfile
# Uncomment if you need to configure the proxy.
# You can init these variables by using --build-arg during the docker build
# Example : docker build [...] --build-arg http_proxy=http://<user>:<password>@<host>:<port>
ENV HTTP_PROXY=$http_proxy
ENV HTTPS_PROXY=$https_proxy
ENV NO_PROXY=$no_proxy

[...]

# Uncomment if you need to configure the proxy.
#RUN npm config set proxy $HTTP_PROXY
  1. Construire l'image en passant les informations du proxy en paramètres

Exemple :

docker build -t greenit-analysis-cli \
  --build-arg http_proxy=http://<user>:<password>@<host>:<port> \
  --build-arg https_proxy=https://<user>:<password>@<host>:<port> \
  --build-arg no_proxy=<no_proxy> \
  .

Usage

Analyse

Construction du fichier d'entrée

Construire le fichier <url_input_file> qui liste les URL à analyser. Le fichier est au format YAML.

Sa structure est la suivante :

Paramètre Type Obligatoire Description
url string Oui URL de la page à analyser
name string Non Nom de la page à analyser affiché dans le rapport
waitForSelector string Non Attend que l'élément HTML définit par le sélecteur CSS soit visible
waitForXPath string Non Attend que l'élément HTML définit par le XPath soit visible
waitForNavigation string Non Attend la fin du chargement de la page. 4 valeurs possibles : load, domcontentloaded, networkidle0, networkidle2
screenshot string Non Réalise une capture d'écran de la page à analyser. La valeur à renseigner est le nom de la capture d'écran. La capture d'écran est réalisée même si le chargement de la page est en erreur.
actions list Non Réalise une suite d'actions avant d'analyser la page

Conditions d'attente

Le paramètre waitForNavigation exploite les fonctionnalités de Puppeteer pour détecter la fin de chargement d'une page sans passer par un sélecteur CSS ou un XPath :

Plus de détails ici : https://github.com/puppeteer/puppeteer/blob/main/docs/api.md

Par défaut, si aucun des paramètres de type waitFor n'est défini, alors l'outil considère que la navigation est terminée lorsque l'événement load est déclenché.

Exemple de fichier url.yaml :

# Analyse l'URL collectif.greenit.fr
- name : 'Collectif GreenIT.fr'
  url : 'https://collectif.greenit.fr/'

# Analyse l'URL collectif.greenit.fr/outils.html en spécifiant une condition d'attente via un sélecteur CSS
# Réalise une capture d'écran de la page
- name : 'Les outils du collectif GreenIT.fr'
  url : 'https://collectif.greenit.fr/outils.html'
  waitForSelector: '#header'
  screenshot: 'output/screenshots/outils.png'

# Analyse l'URL collectif.greenit.fr/index_en.html en spécifiant une condition d'attente via un XPath
- url : 'https://collectif.greenit.fr/index_en.html'
  waitForXPath: '//section[2]/div/h2'

Actions

Les actions permettent de définir un parcours utilisateur plus complexe avant de lancer l'analyse.

Il est possible de définir une liste d'actions à travers le champ actions qui est de type liste. La forme d'une action est la suivante :

Paramètre Type Obligatoire Description
name string Non Non de l'action
type string Oui Type de l'action : click, scroll, select, text
element string Non Element du DOM sur lequel l'action doit être exécutée. De type CSS selector
pageChange boolean Non Si true, indique que l'action déclenche un changement de page. Permet d'avoir un calcul des indicateurs dédié à la nouvelle page. Valeur par défaut : false.
timeoutBefore string Non Temps d'arrêt avant d'exécuter l'action (en millisecondes). Valeur par défaut : 1000
waitForSelector string Non Attend que l'élément HTML définit par le sélecteur CSS soit visible
waitForXPath string Non Attend que l'élément HTML définit par le XPath soit visible
waitForNavigation string Non Attend la fin du chargement de la page. 4 valeurs possibles : load, domcontentloaded, networkidle0, networkidle2
screenshot string Non Réalise une capture d'écran de la page, après avoir réalisé l'action. La valeur à renseigner est le nom de la capture d'écran. La capture d'écran est réalisée même si l'action est en erreur.

Les conditions de type waitFor peuvent être réutilisées afin de définir une condition d'attente après l'exécution de l'action. Elles restent optionnelles. La capture d'écran, le cas échéant, est réalisée après cette condition d'attente.

Des paramètres supplémentaires peuvent être nécessaires selon le type de l'action.

click

Ce type d'action permet de simuler un clic sur un élément de la page.

Ce type d'action nécessite les paramètres supplémentaires :

Paramètre Type Obligatoire Description
element string Oui Element du DOM sur lequel le clic est réalisé. De type CSS selector

Exemple :

- name : 'Collectif GreenIT.fr écoindex'
  url : 'https://collectif.greenit.fr/'
  actions:
    - name : 'Clic sur Découvrez nos outils'
      type: 'click'
      element : 'a[title="Nos outils"]'
      pageChange: true
      timeoutBefore: 1000
      waitForSelector: '#header'
scroll

Ce type d'action permet de simuler un utilisateur qui scroll vers le bas de la page.

Ce type d'action n'a pas de paramètre supplémentaire.

Exemple :

- name : 'ecoconceptionweb.com'
  url : 'https://ecoconceptionweb.com/'
  actions:
    - name : "Scroll auto vers le bas de la page"
      type : 'scroll'
select

Ce type d'action permet de simuler la sélection d'une ou plusieurs valeurs dans une liste déroulante.

Ce type d'action nécessite les paramètres supplémentaires :

Paramètre Type Obligatoire Description
element string Oui Element du DOM représentant la liste déroulante. De type CSS selector
values list Oui Liste des valeurs à sélectionner

Exemple :

- name : 'ecoconceptionweb.com'
  url : 'https://ecoconceptionweb.com/'
  actions:
    - name : "Saisie du choix Proposer dans le select Sujet"
      type : 'select'
      element : '#subject'
      values: ['proposer']
text

Ce type d'action permet de simuler la saisie d'un texte dans un champ d'un formulaire par exemple.

Ce type d'action nécessite les paramètres supplémentaires :

Paramètre Type Obligatoire Description
element string Oui Element du DOM dans lequel le texte est saisi. De type CSS selector
content string Oui Contenu du texte à saisir

Exemple :

- name : 'Collectif GreenIT.fr écoindex'
  url : 'https://collectif.greenit.fr/'
  actions:
    - name : "Remplir l'email dans le formulaire de contact"
      type : 'text'
      element: '#form_email'
      content: 'john.doe@mail.com'
      timeoutBefore: 1000

Commande

greenit analyse <url_input_file> <report_output_file>

Paramètres obligatoires :

Un exemple de fichier listant les scénarios à analyser se trouvent dans le dossier samples.

Paramètres optionnels :

Choix :

Usage avec Docker

  1. Déposer le fichier <url_input_file> dans le dossier /<path>/input.
  2. Lancer l'analyse : 
    docker run -it --init --rm --cap-add=SYS_ADMIN \
-v /<path>/input:/app/input \
-v /<path>/output:/app/output  \
-e TZ=<timezone> \
--name GreenIT-Analysis \
greenit-analysis-cli

📝 Remarque : il faut définir la variable d'environnement TZ pour définir votre timezone afin d'afficher correctement les dates dans les rapports. Exemple de timezone : TZ=Europe/Paris.

💡 Astuce : afin de consulter les captures d'écran prises par l'outil, vous pouvez soit les enregistrer dans le dossier /app/output et bénéficier ainsi du point de montage existant, soit créer un point de montage dédié aux captures d'écran.

  1. Récupérer les résultats dans votre dossier /<path>/output

Redéfinir les variables URL_PATH et RESULTS_PATH

Vous pouvez redéfinir les variables URL_PATH et RESULTS_PATH si vous souhaitez changer le nom des fichiers ou leur emplacement.

Exemple :

docker run -it --init --rm --cap-add=SYS_ADMIN \
  -v /<path>/input:/app/input \
  -v /<path>/output:/app/output  \
  -e TZ=<timezone> \
  -e "URL_PATH=/app/input/myapp_url.yaml" \
  -e "RESULTS_PATH=/app/output/results_20210101.xlsx" \
  --name GreenIT-Analysis \
  greenit-analysis-cli

Surcharger l'instruction CMD définie dans le Dockerfile

Vous pouvez surcharger la commande renseignée par défaut dans le Dockerfile.

Exemple :

docker run -it --init --rm --cap-add=SYS_ADMIN \
  -v /<path>/input:/app/input \
  -v /<path>/output:/app/output  \
  -e TZ=<timezone> \
  --name GreenIT-Analysis \
  greenit-analysis-cli \
  greenit analyse /app/input/url.yaml /app/output/results.xlsx --max_tab=1 --timeout=15000 --retry=5

Lancer l'analyse avec la configuration d'un proxy

Vous pouvez déposer le fichier proxy.yaml dans le dossier /<path>/input et lancer le conteneur :

docker run -it --init --rm --cap-add=SYS_ADMIN \
  -v /<path>/input:/app/input \
  -v /<path>/output:/app/output  \
  -e TZ=<timezone> \
  --name GreenIT-Analysis \
  greenit-analysis-cli \
  greenit analyse /app/input/url.yaml /app/output/results.xlsx --proxy=/app/input/proxy.yaml

Formats des rapports

Excel (xlsx)

Prérequis :

Exemple :

greenit analyse /app/input/url.yaml /app/output/results.xlsx --format=xlsx

Le rapport Excel est composé :

Exemple d'un rapport :

Onglet global du rapport Excel

Onglet d'une URL analysée dans le rapport Excel

HTML

Prérequis :

Exemple :

greenit analyse /app/input/url.yaml /app/output/global.html --format=html

Le rapport HTML est composé :

Exemple d'un rapport :

Page globale du rapport HTML

Page d'un scénario analysé dans le rapport HTML

Page d'un scénario analysé incluant un changement de page dans le rapport HTML

InfluxDB/Grafana

Prérequis :

Les données seront envoyées sur influxdb et peuvent être visualisées avec un outil comme Grafana.

Un docker-compose.yml avec un exemple de configuration d'influxdb et de grafana est présent dans le projet. Lors de la première utilisation, quelques étapes de mise en place sont nécessaires :

Ces étapes ne seront pas nécessaires à nouveau. Il faudra toutefois redémarrer au moins le conteneur influxdb avant un test.

Exemple d'usage :

greenit analyse exampleUrl.yaml /app/output/global.html --format=influxdbhtml --influxdb_hostname http://localhost:8086 --influxdb_org organisation --influxdb_token token --influxdb_bucket db0

Exemple de dashboard grafana pour un scénario et une action : Exemple de dashboard grafana

InfluxDB/Grafana + HTML

Prérequis :

Ce paramètre permet à la fois d'envoyer les données dans InfluxDB, les visualiser dans Grafana, et générer un rapport HTML.

La particularité se trouve dans le rapport HTML généré : une colonne supplémentaire s'affiche dans la page globale pour consulter l'évolution dans le temps des indicateurs d'une page en redirigeant vers le board Grafana.

greenit analyse exampleUrl.yaml --format=influxdb --influxdb_hostname http://localhost:8086 --influxdb_org organisation --influxdb_token token --influxdb_bucket db0

Page globale du rapport HTML généré avec l'option influxdbhtml :

Page globale du rapport HTML généré avec l'option influxdbhtml

ParseSiteMap

greenit parseSitemap <sitemap_url> <yaml_output_file>

Paramètres obligatoires :

Flags généraux

Conditions d'utilisation

Cet outil fait appel à une API ne permettant pas son utilisation à des fins commerciales.