@oaklean/profiler-jest-environment
A jest environment to collect energy measurements on source code level during test execution.
Supports Jest versions v28, v29 and v30.
Table of Contents
Usage
Installation
npm add --save-dev @oaklean/profiler-jest-environment
Configure Jest
Add the @oaklean/jest-profiler-environment to the jest config:
Adjust the jest config like this:
module.exports = {
...
testEnvironment: '@oaklean/profiler-jest-environment/env.js', // add this line
globalSetup: '@oaklean/profiler-jest-environment/setup.js', // add this line
globalTeardown: '@oaklean/profiler-jest-environment/teardown.js', // add this line
...
}
Configure Oaklean
The CLI can be used to easily setup a .oaklean config file.
- Install oaklean:
npm add @oaklean/profiler - Run the init script:
npx oak init - It will ask you which sensor interface should be used for energy measurements:
Select a sensor interface (recommended for your platform: perf)
None (pure cpu time measurements)
powermetrics (macOS only)
❯ perf (Linux only)
windows (Windows only)
energy measurements on Linux (Intel & AMD CPUs only)
- The cli asks you to confirm your choice and generates a valid
.oakleanand.oaklean.localconfig file for you:
✔ Select a sensor interface (recommended for your platform: powermetrics) perf (Linux only)
[Oaklean] [Main Config]
{
"extends": ".oaklean.local",
"exportOptions": {
"outDir": "profiles/",
"outHistoryDir": "profiles_history/",
"rootDir": "./",
"exportV8Profile": false,
"exportReport": true,
"exportSensorInterfaceData": false
},
"projectOptions": {
"identifier": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
},
"runtimeOptions": {
"seeds": {},
"v8": {
"cpu": {
"sampleInterval": 1
}
}
}
}
[Oaklean] [Local Config]
{
"runtimeOptions": {
"sensorInterface": {
"type": "perf",
"options": {
"outputFilePath": "energy-measurements.txt",
"sampleInterval": 100
}
}
}
}
? Is this OK? (yes) (Y/n)
Available Sensor Interfaces
| SensorInterface | Operating System |
|---|---|
| powermetrics | macOS |
| perf | linux |
| windows | windows |
If you want to how to setup the Sensor Interfaces and how to make them work with Docker you can read more about it here
⚠️ Most Sensor Interfaces need root privileges
Look into the Sensor Interface Docs to see how you can run them without root privileges
🔍 How measurements work
During the test execution measurements are collected with a sample based approach. So for every n - microseconds it collects a v8 cpu profile and energy measurements of the sensor interface. You can adjust the sampling rate with thesampleIntervaloptions in the.oakleanconfig file above.
Collect Energy Measurements
⚠️ The measurement data is NOT automatically collected
To enable measurements during test execution you must set an environment variable beforehand (ENABLE_MEASUREMENTS=1). When running Jest tests with this environment variable, the measurement data should be saved in the specified output directory.
:pinched_fingers: For more accurate measurement results
It is mandatory to run Jest with the --runInBand option. This ensures that the tests are executed sequentially and not in different threads: npx jest --coverage --runInBand.
Execute the tests:
ENABLE_MEASUREMENTS=1 npx jest --coverage --runInBand
Interpret The Measurements
The Oaklean VSCode Extension lets you to interpret the measurements. It integrates the energy measurements directly into your IDE.
You can find it here:
It provides code highlighting to point out which source code locations consume the most energy:
It also provides multiple features to determine the components that consume the most energy, including node modules:
