Skip to content

A command-line tool to industrialize web quality measurement

License

Notifications You must be signed in to change notification settings

faberNovel/heart

Repository files navigation

Violet square with rounded corners, featuring a heart in the form of a cloud of dots. Some of the dots are interconnected

A command-line tool to industrialize web quality measurement.

npm codecov Known Vulnerabilities

Description

Heart is a tool that centralize the use of famous web quality measurement services (Google Lighthouse, GreenIT Analysis or Mozilla Observatory) in a unique CLI.

With his modular approach, it makes easy to process the analysis results into a database to track metrics over time, or send them into a communication tool like Slack.

Moreover the command-line interface allows a smooth integration into a CI/CD chain.

Example of use

Exemple scenario:

  • analyze https://heart.fabernovel.com/ using the Google Lighthouse service.
  • receive the main metrics and advices on a heart Slack channel when the analysis is over.
  • store the results in a MySQL database.

Manual, with NPM packages

  1. Install the packages

    npm install @fabernovel/heart-lighthouse @fabernovel/heart-slack @fabernovel/heart-mysql
  2. Set the credentials for Slack (API key) and MySQL (database URL)

    echo HEART_SLACK_API_TOKEN=xoxb-rest-of-token >> .env
    echo HEART_MYSQL_DATABASE_URL=login:password@127.0.0.1:3306 >> .env
  3. Create a Slack channel named heart and a database with the same name.

  4. Start the analysis

    npx heart lighthouse --config '{"url":"https://heart.fabernovel.com/"}'

Once the analysis is over, you will receive a Slack notification to quickly identify what can be improved:

Analyzed URL, overall grade over 100, several metrics like Speed Index, First Contentful Paint and advices for improvements

And the results will be stored in a report table, which you can exploit with tools like Grafana:

Analyzed URL, overall grade over 100, several metrics like Speed Index, First Contentful Paint and advices for improvements

For more options, have a look at the help by using npx heart -h

Packaged, with the Docker image

Heart is also available as a Docker image.

With the example scenario given previously, the Docker image is used as follow:

docker run --rm\
    --env HEART_SLACK_API_TOKEN=xoxb-rest-of-token\
    --env HEART_MYSQL_DATABASE_URL=login:password@127.0.0.1:3306\
    fabernovel/heart:latest\
    lighthouse --config '{"url":"https://heart.fabernovel.com"}' --only-listeners=mysql,slack

Automated, with the GitHub Action

If you're using GitHub, you can simplify the integration of Heart in your CI scripts by using the GitHub Action.

With the example scenario given previously, the GitHub Action is used as follow:

- uses: faberNovel/heart-action@v4
  with:
    analysis_service: lighthouse
    listener_services_only: mysql,slack
    mysql_database_url: ${{ secrets.MYSQL_DATABASE_URL }}
    slack_api_token: ${{ secrets.SLACK_API_TOKEN }}

Design

Heart has been designed to be as light as possible, which explains its modular approach: you only install what you need.

To do so, Heart is divided in 3 types of modules.

Modules types

Type Mission Example
Runner Starts an analysis using the CLI or the HTTP API
Analysis Analyzes URLs using third-party services using GreenIT Analysis
Listener Do thing with the results of the analysis send them into a Slack channel

The minimum setup you need to run Heart, is to have the Heart CLI runner module and a single analysis module.

Modules list

Name Type Purpose
Heart API Runner Exposes an HTTP API that starts an analysis when it is requested
Heart CLI Runner Control the other modules by using a CLI
Heart GreenIT Analysis Analyzes URLs with GreenIT Analysis
Heart Lighthouse Analysis Analyzes URLs with Google Lighthouse
Heart Observatory Analysis Analyzes URLs with Mozilla Observatory
Heart SSL Labs Server Analysis Analyzes URLs with Qualys SSL Labs Server
Heart MySQL Listener Stores the results of the analysis into a MySQL database
Heart Slack Listener Sends the results of the analysis to a Slack channel