GreenFrame Update: Easier Scenarios, Env Vars, and Improved Security

GreenFrame.io allows web developers to measure and reduce the carbon footprint of their websites. We recently added some major features to greenframe-cli, the open-source core of GreenFrame.

Using External Modules In A Scenario

GreenFrame scenarios can now import external modules. This was the most requested feature by our users, and it opens up many possibilities.

Here is an example of a scenario using an external library to log in to a website:

const { loginToWebSite } = require('externalLoginLibrary');

const scenario = async (page) => {
    await loginToWebSite('login', 'password');
    await page.goto('', { waitUntil: 'networkidle' });
    await page.scrollToEnd();
    //do some actions
    await page.waitForNetworkIdle();
};

module.exports = scenario;

Thanks to this feature, you can now use any external module in your scenarios. For example, winston for logging, moment for computing dates, or whatever can help.

This also allows you to refactor your code and extract code shared between several scenarios.

We've added a specific section in the "Writing a scenario" documentation to explain how to use external modules in your scenarios.

Tip: Scenarios must use require() to import packages, as import isn't supported yet.

Using Environment Variables

The second major evolution is that GreenFrame now allows you to access environment variables. Secret values like API keys, test usernames and passwords can be stored outside of the code and just read when running analysis.

For example, if you want a scenario to log in to your website before performing some actions, the login and password just need to be defined in your execution context or in some external .env file.

const { loginToWebSite } = require('externalLoginLibrary');
const login = process.env.ENV_VAR_LOGIN;
const password = process.env.ENV_VAR_PASSWORD;

const scenario = async (page) => {
    await loginToWebSite(login, password);
    await page.goto('', { waitUntil: 'networkidle' });
    await page.scrollToEnd();
    //do some actions
    await page.waitForNetworkIdle();
};

module.exports = scenario;

You can set environment variables in you shell, in an envfile, or directly in the .greenframe.yml config file, as in the following example:

baseURL: YOUR_APP_BASE_URL
scenarios:
    - path: PATH_TO_YOUR_SCENARIO_FILE
      name: My first scenario
      threshold: 0.1
projectName: YOUR_PROJECT_NAME
envVar:
    - ENV_VAR_LOGIN: johndoe
    - ENV_VAR_PASSWORD: mypassword

Check the CLI options documentation for more details.

Improved Security

Previously, GreenFrame was running user scenarios in a sandbox by combining two specific tools:

• The vm2 library, which has been deprecated because of critical security issues.
• The eval() command, used to execute the scenario script, which can lead to many risks depending on what is written in the script.

We removed them both.

Now, GreenFrame imports user scenario like any regular JS package. This major change is what opens up the ability to use external packages in the scenarios.

Breaking Changes

These changes are available in greenframe-cli version 2.0. Here are the breaking changes you need to be aware of:

The --distant option is no longer supported

It's no longer possible to execute a custom scenario on GreenFrame servers. This possibility was given by the --distant option, which is now removed.

Only simple visit scenarios configured on GreenFrame.io can now run on our servers.

This feature wasn't broadly used anyway, so this breaking change shouldn't be impacting many users.

Scenario functions must be exported

The scenarios written for GreenFrame 1.6 or older should be modified to run on GreenFrame 2.0.

The scenario function has to be exported so it can be imported as a module by the GreenFrame runner.

The update is simple: For each scenario file, modify the first and the last line as follows:

-async (page) => {
+const myOwnScenario = async (page) => {
    // scenario content
};

+module.exports = myOwnScenario;

The GreenFrame Documentation was updated to reflect this change.

Warning: The export myOwnScenario; syntax is not recognized

Conclusion

These changes make greenframe-cli much more flexible, and should allow more developers to integrate it into their CI pipelines.

The Greenframe documentation is up to date with these changes. Check it out!

If you haven't tried it yet, give GreenFrame a try to see how it can help you measure and reduce the environmental impact of your website.