Skip to main content

Getting Started

GreenFrame Enterprise is currently in beta. To get an invitation, contact us at [email protected].

Activating Your Account#

Once you're a registered GreenFrame Enterprise user, you should receive an email containing a link to activate your account, as well as an API token. Keep it, you will need it later.

To install GreenFrame CLI, type the following command in your favorite terminal:

curl https://assets.greenframe.io/install.sh | bash

To verify that GreenFrame CLI has correctly been installed, type:

$ greenframe version
enterprise-cli/0.0.11 linux-x64 node-v14.15.2
info

The GreenFrame CLI currently runs only on Linux x64, and requires Docker to be installed.

Writing Your First Scenario#

Go to your the root folder of the app you want to analyse, and paste the following scenario:

./scenario.js
async (page) => {
// Go to the url passed to the command line (see below)
await page.goto('', { waitUntil: 'networkidle' });
await page.waitForTimeout(3000); // Wait for 3 seconds
await page.scrollToElement("footer"); // Scroll to the bottom of the page (change the element name depending on your markup)
await page.waitForNetworkIdle(); // Wait for every request to be answered - like a normal user would do
};

Run the following command to test the scenario:

$ greenframe open ./scenario.js YOUR_WEBSITE_URL

You should see a Chrome browser executing your scenario.

If it works as intended, you're all set for your first analysis!

info

You must have Docker installed on your machine to run this command.

Running Your First Analysis#

You can now measure the carbon footprint of this scenario using the headless browser included in the GreenFrame CLI.

First of all, provide your API token in the current shell:

$ export GREENFRAME_SECRET_TOKEN=YOUR_API_TOKEN
info

Don't forget to include this token in CI environments, too!

Next, run the analysis locally with the following command:

$ greenframe analyze ./scenario.js YOUR_WEBSITE_URL -p YOUR_PROJECT_NAME
Starting GreenFrame analysis for YOUR_WEBSITE_URL
โœ” Reading scenario file
โœ” Retrieving GreenFrame Project
โœ” Retrieving Git information
โœ” Launching analysis
โœ” Analysis is in progress locally
โœ” Docker version 20.10.7, build f0df350
โœ” Running analysis
โœ… Success!
The estimated footprint is 0.048 Wh ยฑ 3.2%.
Check the details of your analysis at https://app.greenframe.io/YOUR_ANALYSIS_ID

The details of the analysis will be available at https://app.greenframe.io/YOUR_ANALYSIS_ID. By logging in, you can also see the history of your analyses, and compare two analyses to see the changes.

Adjusting The Success/Fail Threshold#

The greenframe analyze command measures the footprint of a scenario, but doesn't make any decision to determine whether the footprint is good or bad.

You can decide that any analysis with a footprint above a certain threshold is considered a failure, and any analysis below that threshold is considered a success. This is especially useful when using GreenFrame in a CI environment, where you want to make sure that a change in the code doesn't increase the energy consumption of your scenario.

Use the --threshold option to input a success/fail threshold, which is the maximum amount of energy in Wh that your scenario should consume to let the analyze command return successfully (exit 0).

$ greenframe analyze ./scenario.js YOUR_WEBSITE_URL -p YOUR_PROJECT_NAME --threshold 0.1

In this example, an analysis with a footprint of 0.048 Wh will succeed, but one with a footprint of 0.123 Wh will fail.

Improving The Analysis Precision#

GreenFrame computes the precision of your analysis by comparing the footprint across several samples. By default, GreenFrame runs your scenario three times.

A good precision should be less than 2%. If your analyses have a precision score greater than 2%, this will make detection of changes in the footprint harder - as a 2% change may not be significant.

There are several ways to improve the precision of your analysis:

  1. Avoid pages with variable content in your scenarios. For instance, a page that loads a random wallpaper will have a variable footprint on every analysis. Run your scenarios on a fixed data set instead.
  2. Use a longer scenario: As the analysis score depends on the duration of the scenario, the longer it takes to run a scenario, the better the precision. Try to aim for a scenario of at least 10 seconds.
  3. Increase the number of samples: Pass the --samples [nb] option to execute the scenario more than three times, e.g. --samples 5
  4. Run the analysis on a server that has stable load (preferably not a CI container) or on the GreenFrame cloud (see below).

Running An Analysis On GreenFrame Servers#

Running analyses locally (or in your CI build container) has a few limitations:

  • The analysis precision may be too low due to variations in the system load.
  • You must have Docker installed to run the browser container.

Alternatively, you can run your analysis on the GreenFrame servers. This should improve the precisions to less than 2% for a scenario of at least 10 seconds.

To run an analysis on the GreenFrame servers, pass the --distant option to the analyze command:

$ greenframe analyze ./scenario.js YOUR_WEBSITE_URL -p YOUR_PROJECT_NAME --distant

The constraint is that the URL to analyze must be accessible from the GreenFrame servers. So this won't work when running the site to test on a local machine. To overcome that limitation, you can use tunneling.

Writing A Complex Scenario#

To estimate the carbon footprint of your application, GreenFrame execute a Playwright scenario in a sandboxed container.

GreenFrame exposes a custom Page object to Playwright scenarios. This Page object contains additional methods that better reflect real-life user interactions. Using these methods leads to a more accurate carbon footprint estimate.

You can find the documentation for these methods in the "Scenario" section.