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 versionenterprise-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};

Also create a .greenframe.yml configuration file:

baseURL: http://localhost:3000scenarios:  - path: ./scenario.js    name: My first scenario

Check here how you can completely configuring the CLI.

Run the following command to test the scenario:

$ greenframe open

You should see a Chrome browser executing your scenario.

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

Running Your First Analysis#

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

Then, 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
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
Analysis complete !
Result summary:
โœ… My first scenario completedThe estimated footprint at 0.025 Wh ยฑ 1.4% is under the limit configured at 0.1 Wh.
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.

info

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

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).

In your .greenframe.yaml add threshold: 0.1 in mWh.

baseURL: http://localhost:3000scenarios:  - path: ./scenario.js    name: My first scenariothreshold: 0.1

Then run your analysis.

$ greenframe analyze

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: Add 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, add the distant option in your .greenframe.yml:

baseURL: http://localhost:3000scenarios:  - path: ./scenario.js    name: My first scenariothreshold: 0.1distant: true

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.