Skip to main content

Configuring the CLI

info

Type greenframe help if you are lost!

Using a Configuration File#

At the root of your project, create a .greenframe.yml file :

baseURL: YOUR_APP_BASE_URLscenarios:  - path: PATH_TO_YOUR_SCENARIO_FILE    name: My first scenario    threshold: 0.1projectName: YOUR_PROJECT_NAMEsamples: 3distant: falsecontainers:  - "CONTAINER_NAME"  - "ANOTHER_CONTAINER_NAME"databaseContainers:  - "DATABASE_CONTAINER_NAME"

Then in the same folder, GreenFrame CLI will automatically take the configuration file.

baseURL: Your app base URL (e.g http://localhost:3000), note that page.goto in your scenario method will be affected by this base url.

scenarios: Enter a list of scenarios that you want to run.

  • path: Absolute path regarding to the configuration file to locate your scenario.
  • name: Add a name to your scenario to identify it inside the GreenFrame app.
  • threshold: in Wh, the scenario will fail if the consumption passes this limit.

projectName: A name of your project, if the project doesn't exist, it will be created. It's used to manage the history of your project. If you ommit it, GreenFrame CLI will search a PROJECT_NAME env variable or will take the name of your project.

samples: (default: 3) Number between 2 and 10 of runs of your scenarios. A high number will improve the duration of your CI but will also increase the precision.

distant: (default: false) Distant mode is used to run an analysis by using GreenFrame Server. Use this mode if your CI is unstable and if between 2 sames analyses you have a big difference. By using this mode you canno't track other containers than the browser.

containers: A list of your server containers name (like api, proxy or cache system) that you want to measure during an analysis. Enter the same name as you see it when typing docker ps, you can also fix it inside the docker-compose with by using the container_name field

databaseContainers: A list of your database containers name (like PostgreSQL or mongoDB) that you want to measure during an analysis. Enter the same name as you see it when typing docker ps, you can also fix it inside the docker-compose with by using the container_name field

Using Another Configuration File#

You can specify another location for your .greenframe.yml file by using the -C command:

Example : greenframe analyze -C ./another_folder/.greenframe.ci.yml

Running a GreenFrame Analysis with Custom Hosts#

Sometimes your app should run on a specific URL in local which is not localhost. You have wrote in your /etc/hosts a mapping between 127.0.0.1 and your specific URL.

GreenFrame CLI cannot access to this mapping and you should pass it to the CLI during an analyze in order to let the CLI to access to theses URLs.

In your .greenframe.yml you can add the following lines:

extraHosts:  - "extra-host.com"  - "another.extra-host.com"

Running a Scenario in debug mode#

To debug a scenario with a real browser, use the open command:

greenframe open SCENARIO BASEURL

Example : greenframe open ./scenario.js http://localhost:3000

A Chromium or Google chrome browser is required to be installed on your computer to execute this command correctly. If it's not the case you can install chromium by typing the following command :

sudo apt-get install chromium-browser

All analyze Command Options#

You can directly pass options as analyze command parameters to override how your analysis will be performed.

Using One Line Command#

If for some reasons you don't want to perform an analysis by using a .greenframe.yml you can specify the baseURL of your project and the path to your scenario file directly in one command:

Example: greenframe analysis scenario.js http://localhost:3000

info

Please note by using one line command, you can't run multiple scenarios.

--projectName Option#

To follow evolution of your analysis made on GreenFrame, use --projectName or -p to identify your project in GreenFrame.

The project name can be passed as the GREENFRAME_PROJECT_NAME environment variable in the CI environment.

If the project name is not specified through the command option or the environment variable, GreenFrame will automatically retrieve your git's project name and use it as the project name. Please note that the command must be executed in the corresponding git project for this to work.

Example: greenframe analyze scenario.js http://localhost:3000 --projectName my_awesome_project

--threshold Option#

When using greenframe analyze in a CI environment, you typically want the build to fail if the carbon footprint exceeds a predefined threshold in Watt.hours. Use the --threshold option (or -t) for that.

Example : greenframe analyze scenario.js http://localhost:3000 --threshold 0.05

--commitMessage Option#

When using greenframe analyze in a CI environment, you want to know for which commit GreenFrame made an analysis. GreenFrame CLI automatically retrieves it but in some CI you can't have access to .git folder and this detection will fail. You can pass it and override the commit message detection by using the --commitMessage option (or -c).

Example : greenframe analyze scenario.js http://localhost:3000 --commitMessage "Add login feature"

--commitId Option#

When using greenframe analyze in a CI environment, you want to know for which commit GreenFrame made an analysis. GreenFrame CLI automatically retrieves it but in some CI you can't have access to .git folder and this detection will fail. You can pass it and override the commit ID detection by using the --commitId option.

Example : greenframe analyze scenario.js http://localhost:3000 --commitId "SHA1_COMMIT_ID"

info

Please note if this variable is not set, you will not be able to perform automatic comparison with your default git branch. This git branch can be configured per project inside your settings directly in the application.

--branchName Option#

When using greenframe analyze in a CI environment, you want to know for which branch GreenFrame made an analysis. GreenFrame CLI automatically retrieves it but in some CI you can't have access to .git folder and this detection will fail. You can pass it and override the branch name detection by using the --branchName option (or -b).

Example : greenframe analyze scenario.js http://localhost:3000 --branchName "feat/login"

--samples Option#

When using greenframe analyze in a CI environment, you might want to change the number of samples that are performed by the analysis in order to improve the precision. Use the --samples option (or -s). Its default value is 3.

Example : greenframe analyze scenario.js http://localhost:3000 --samples 5

--distant Option#

When using greenframe analyze in a CI environment, you must have docker installed. The analysis will be performed locally and the GreenFrame CLI will start a container in order to run your scenario.

It's fast but if you have an unstable CI environment (e.g : Free tier), you might want to use a more stable runner.

GreenFrame provides you with distant workers to run with your CLI. By passing --distant (or -d) the GreenFrame CLI will execute this analysis on our servers.

Example : greenframe analyze scenario.js http://localhost:3000 --distant

info

Please take in account that your analysis can be queued for a certain amount of time before being executed with the distant mode.

--configFile Option#

If your configuration file is located to another path or is named differently than .greenframe.yml, you can provide a path to this file by using the --configFile or -C argument.

Example: greenframe analyze --configFile ./config/mygreenframefile.yml