k6 – Using xk6-dotenv for Managing Environment Variables

As development progresses, the number of environment variables that need to be managed increases.
The same issue occurs with k6.
In this article, I’ll introduce the k6 extension xk6-dotenv, which is useful for managing environment variables.

xk6-dotenv: https://github.com/szkiba/xk6-dotenv

Prerequisites

If you haven’t installed xk6 yet, start with setting up the environment.
For those without a Go environment, please set it up separately.

go install go.k6.io/xk6/cmd/xk6@latest

Installing xk6-dotenv

Let’s build the k6 command with the following command.
Since we’re developing with TypeScript, we’re also installing xk6-ts.

xk6 build 
--with github.com/szkiba/xk6-ts@latest 
--with github.com/szkiba/xk6-dotenv@latest

Usage

Prepare a .env file in the root directory of your project.

AMOUNT_OF_INDEX_SIZE_FOR_TEST_DATA=10000
DEBUG=true
ENV=local
SAMPLE_PRODUCT_ENDPOINT=localhost:3000
REDIS_ENDPOINT=redis://localhost:6379

ref: https://github.com/gonkunkun/k6-template/blob/main/.env.sample

Use __ENV to load environment variables from anywhere you want.

import { toBoolean } from './common'

export const DEBUG =toBoolean(__ENV.DEBUG) || false
export const ENV = __ENV.ENV || 'local'
export const CONFIG_PATH = __ENV.CONFIG_PATH || '../src/sample-product/configs/smoke.json'
export const REDIS_ENDPOINT = __ENV.REDIS_ENDPOINT || 'redis://localhost:6379'
export const AMOUNT_OF_INDEX_SIZE_FOR_TEST_DATA = __ENV.AMOUNT_OF_INDEX_SIZE_FOR_TEST_DATA || 10000
export const SAMPLE_PRODUCT_ENDPOINT = __ENV.SAMPLE_PRODUCT_ENDPOINT || 'localhost'

ref: https://github.com/gonkunkun/k6-template/blob/main/src/sample-product/common/env.ts

That’s it!

When executing k6, it automatically reads the contents of the .env file and loads them into environment variables.

Additional Note

This feature became so easy to use only recently.
There was an update on April 2, 2024.
https://github.com/szkiba/xk6-dotenv/releases/tag/v0.2.0

Before that, you needed to include the following process to read the file:

const _ENV = parse(open("../.env"))

With the update, it now automatically loads into environment variables without this process.

If you’re using an older version of the extension, you might encounter errors like:

~/D/g/template-of-k6 ❯❯❯ npm run smoke:sample-product                   ✘ 130 main

> typescript@1.0.0 smoke:sample-product /Users/Documents/github/template-of-k6
> XK6_TS=false ./k6 run ./dist/loadTest.js -e CONFIG_PATH=./src/sample-product/configs/smoke.json

          /      |‾‾| /‾‾/   /‾‾/   
     /  /       |  |/  /   /  /    
    /  /        |     (   /   ‾‾  
   /             |  |   |  (‾)  | 
  / __________   |__| __ _____/ .io

ERRO[0000] GoError: unknown module: k6/x/dotenv
        at go.k6.io/k6/js.(*requireImpl).require-fm (native)
        at 139 (webpack://typescript/external%20commonjs%20%22k6/x/dotenv%22:1:34(21))
        at __webpack_require__ (webpack://typescript/webpack/bootstrap:19:0(26))
        at 432 (file:///Users/Documents/github/template-of-k6/dist/loadTest.js:19:81(62))
        at __webpack_require__ (webpack://typescript/webpack/bootstrap:19:0(26))
        at webpack://webpack/runtime/make%20namespace%20object:7:0(29)
        at file:///Users/Documents/github/template-of-k6/dist/loadTest.js:629:3(49)
        at file:///Users/Documents/github/template-of-k6/dist/loadTest.js:634:12(3)  hint="script exception"
npm ERR! code ELIFECYCLE
npm ERR! errno 107
npm ERR! typescript@1.0.0 smoke:sample-product: `XK6_TS=false ./k6 run ./dist/loadTest.js -e CONFIG_PATH=./src/sample-product/configs/smoke.json`
npm ERR! Exit status 107
npm ERR! 
npm ERR! Failed at the typescript@1.0.0 smoke:sample-product script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

Follow the example PR for fixes:
PR: https://github.com/gonkunkun/k6-template/pull/5

It’s a short article, but that’s all.
Enjoy your k6 life!