k6-cucumber-steps 1.0.0

package/.env

@@ -0,0 +1,17 @@
+# .env
+TEST_ENVIRONMENT=STAGING
+APP_VERSION=1.0.0
+BROWSER=Chrome 100.0.4896.88
+PLATFORM=Windows 10
+PARALLEL=Scenarios
+EXECUTED=Remote
+TAGS=@loadTest
+
+# Base URLs
+# API_URL=https://unstable-performance.seamlesshrms.com
+# BASE_URL=https://unstable-performance.seamlesshrms.com
+BASE_URL=https://grafana.com
+
+# Secret Parameters
+API_KEY=Talent123!
+BEARER_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3J1bnRocm91Z2gtdHdvLnNlYW1sZXNzaHJtcy5jb20vYXBpL3YxL2F1dGgvbG9naW4iLCJpYXQiOjE3NDU2MjAwNDEsImV4cCI6MTc0NTYyMzY0MSwibmJmIjoxNzQ1NjIwMDQxLCJqdGkiOiJkQmZHZW9Takh3MlZ0NEF6Iiwic3ViIjoiMjI2IiwicHJ2IjoiYzIwM2QyYmJmODZhN2IyNzcyZWUyNGNhODIyNzBmOTA5NTgyZjg3YyJ9.WGdq8QMpSZvCJB6cj0hn3xrUIfhIbOE4Ft4bo8u1JKw

package/.env.example

@@ -0,0 +1,17 @@
+# .env
+TEST_ENVIRONMENT=STAGING
+APP_VERSION=1.0.0
+BROWSER=Chrome 100.0.4896.88
+PLATFORM=Windows 10
+PARALLEL=Scenarios
+EXECUTED=Remote
+
+# Base URLs
+API_URL=https://test-api.example.com
+BASE_URL=https://example.com
+AUTH_URL=https://auth.example.com
+PAYMENT_URL=https://payment.example.com
+
+# Secret Parameters
+API_KEY=your-secret-api-key-12345
+BEARER_TOKEN=your_bearer_token_here

package/.github/workflows/k6-load-test.yml

@@ -0,0 +1,35 @@
+name: Node.js Package Workflow
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [lts/*]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+      - name: Install k6
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends k6
+      - name: Verify k6 Installation
+        run: k6 version
+      - name: Install Dependencies
+        run: npm install
+      - name: List Dependencies
+        run: npm list --all
+      - name: Run Load Tests
+        run: npm loadTest

package/.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+        "cucumberopen.cucumber-official"
+    ]
+}

package/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  "cucumber.features": [
+    "src/features/*.feature",
+    "src/features/**/*.feature",
+    "src/features/**/*.k6.feature",
+    "src/features/template/*.feature"
+  ],
+  "cucumber.glue": ["step_definitions/*.js","src/features/stepDefinitions/*.js"
+]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Enyimiri Chetachi Paschal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of **k6-cucumber-steps** (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# k6-cucumber-steps 🥒🧪
+
+<table align="center" style="margin-bottom:30px;"><tr><td align="center" width="9999" heigth="9999 " >
+ <img src="assets/paschal logo (2).png" alt="paschal Logo" style="margin-top:25px;" align="center"/>
+
+#
+
+[![npm version](https://img.shields.io/npm/v/k6-cucumber-steps.svg)](https://www.npmjs.com/package/k6-cucumber-steps)
+[![npm downloads](https://img.shields.io/npm/dt/k6-cucumber-steps.svg)](https://www.npmjs.com/package/k6-cucumber-steps)
+[![License](https://img.shields.io/npm/l/k6-cucumber-steps.svg)](./LICENSE)
+[![Cucumber](https://img.shields.io/badge/built%20with-Cucumber-3178c6.svg)](https://cucumber.io/)
+[![Node.js](https://img.shields.io/badge/node-%3E=18-green.svg)](https://nodejs.org/)
+
+Run [k6](https://k6.io/) performance/load tests using [Cucumber](https://cucumber.io/) BDD syntax with ease.
+
+---
+
+## ✨ Features
+
+- ✅ Cucumber + Gherkin for writing k6 tests
+- ✅ Support for JSON body parsing and escaping
+- ✅ Faker support (`{{faker.name.firstName}}`)
+- ✅ `.env` + `K6.env`-style variable resolution (`{{API_KEY}}`)
+- ✅ Support for headers, query params, stages
+- ✅ Clean-up of temporary k6 files after execution
+- ✅ Built-in support for **distributed load testing** with stages
+- ✅ TypeScript-first 🧡
+
+---
+
+## 📦 Install
+
+```bash
+npm install k6-cucumber-steps
+```
+
+---
+
+## 🚀 Usage
+
+### CLI
+
+```bash
+npx k6-cucumber-steps run --feature ./features/example.feature
+```
+
+### Programmatic
+
+```ts
+import { runK6Feature } from "k6-cucumber-steps";
+
+await runK6Feature("./features/example.feature");
+```
+
+---
+
+## Setup
+
+1. **Environment Variables**: Create a `.env` file in your project root based on the provided `.env.example`:
+
+   ```env
+   BASE_URL=https://api.example.com
+   API_KEY=your_api_key
+   BEARER_TOKEN=your_bearer_token
+   BASIC_USER=your_basic_user
+   BASIC_PASS=your_basic_pass
+   ```
+
+2. **Feature Files**: Write your feature files using the provided step definitions.
+
+## Gherkin Examples
+
+Here’s how you can write a feature file using the provided step definitions:
+
+### Example 1: Test GET Endpoint with No Authentication
+
+```gherkin
+Feature: API Performance Testing
+
+  Scenario: Run load tests with dynamic GET requests
+    Given I have a k6 script for GET testing
+    When I run the k6 script with the following configurations:
+      | virtual_users | duration | http_req_failed | http_req_duration |
+      | 50            | 10       | rate<0.05       | p(95)<3000        |
+    And the following endpoint(s) is/are used:
+      """
+      /api/profile
+      https://reqres.in/api/users?page=2
+      """
+    And when the authentication type is "none"
+    Then the API should handle the GET request successfully
+```
+
+### Example 2: Test POST Endpoint with Bearer Token Authentication
+
+```gherkin
+Feature: API Performance Testing
+
+  Scenario: Run load tests with dynamic POST requests
+    Given I have a k6 script for POST testing
+    When I run the k6 script with the following configurations:
+      | virtual_users | duration | http_req_failed | http_req_duration |
+      | 20            | 60       | rate<0.01       | p(95)<300         |
+    And the authentication type is "bearer_token"
+    And the following endpoint(s) is/are used:
+      """
+      /api/v1/users
+      """
+    And the following POST body is used for "/api/v1/users"
+      """
+      {
+        "username": "{{username}}",
+        "email": "{{faker.internet.email}}"
+      }
+      """
+    Then the API should handle the POST request successfully
+```
+
+## Step Definitions
+
+### Authentication Steps
+
+```gherkin
+When the authentication type is "api_key"
+When the authentication type is "bearer_token"
+When the authentication type is "basic"
+When the authentication type is "none"
+```
+
+### Request Configuration Steps
+
+```gherkin
+Given I have a k6 script for {word} testing
+When I run the k6 script with the following configurations:
+When the request headers are:
+When the following endpoint(s) is/are used:
+When the following {word} body is used for {string}
+```
+
+### Assertion Steps
+
+```gherkin
+Then the API should handle the {word} request successfully
+```
+
+## Test Results
+
+Below is an example of the Cucumber report generated after running the tests:
+
+![Cucumber Report](./assets/k6-cucumber-report.png)
+
+### Explanation of the Report
+
+- **All Scenarios**: Total number of scenarios executed.
+- **Passed Scenarios**: Number of scenarios that passed.
+- **Failed Scenarios**: Number of scenarios that failed.
+- **Metadata**: Information about the test environment (e.g., browser, platform).
+- **Feature Overview**: Summary of the feature being tested.
+- **Scenario Details**: Detailed steps and their execution status.
+
+## 🧼 Temporary Files Clean-up
+
+All generated k6 scripts and artifacts are cleaned automatically after test execution.
+
+---
+
+## 📄 License
+
+MIT License - [@qaPaschalE](https://github.com/qaPaschalE)
+
+```
+
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+
+```

package/cucumber.js

@@ -0,0 +1,26 @@
+/**
+ * @module cucumber
+ * @description
+ * This module configures the Cucumber.js test runner for load testing with k6.
+ * It specifies the paths to feature files, step definitions, and the output format.
+ * It also sets the timeout for each test and allows for filtering tests by tags.
+ */
+const reporter = require("cucumber-html-reporter");
+module.exports = {
+  default: {
+    require: ["step_definitions/world.js", "step_definitions/*.js"],
+    paths: ["src/examples/features/*.feature"],
+    format: ["progress", "json:reports/load-results.json"],
+    timeout: 60000,
+    tags: process.env.TAGS || "@loadTest",
+  },
+};
+
+// // Generate an HTML report after tests complete
+// reporter.generate({
+//   theme: "bootstrap",
+//   jsonFile: "reports/load-results.json",
+//   output: "reports/report.html",
+//   reportSuiteAsScenarios: true,
+//   scenarioTimestamp: true,
+// });

package/generateReport.js

@@ -0,0 +1,24 @@
+const reporter = require("cucumber-html-reporter");
+
+// Configuration for the HTML report
+const options = {
+  theme: "bootstrap", // You can change the theme to 'simple', 'compact', etc.
+  jsonFile: "reports/load-results.json", // Path to the JSON file generated by Cucumber
+  output: "reports/report.html", // Path where you want to save the HTML report
+  reportSuiteAsScenarios: true, // Group scenarios by their name
+  launchReport: true, // Automatically open the report in the browser
+  metadata: {
+    browser: {
+      name: "Chrome" || "unknown",
+      version: "89" || "unknown",
+    },
+    device: "Local test machine",
+    platform: {
+      name: "MacOS",
+      version: "20.04",
+    },
+  },
+};
+
+// Generate the report
+reporter.generate(options);

package/libs/helpers/buildK6Script.js

@@ -0,0 +1,94 @@
+/**
+ * @module generateHeaders
+ * @description
+ * This module generates HTTP headers for API requests based on the specified authentication type.
+ * It supports API key, bearer token, and basic authentication.
+ * Generates HTTP headers based on the specified authentication type.
+ * Supported auth types: api_key, bearer_token, basic.
+ * @param {string} authType - The type of authentication to use.
+ * @param {object} env - The environment variables object.
+ * @returns {object} - The generated headers object.
+ * @throws {Error} - If the authentication type is unsupported.
+ * @example
+ * const headers = generateHeaders('api_key', process.env);
+ * // headers will contain the API key in the x-api-key header.
+ * @example
+ * const headers = generateHeaders('bearer_token', process.env);
+ * // headers will contain the bearer token in the Authorization header.
+ * @example
+ * const headers = generateHeaders('basic', process.env);
+ * // headers will contain the basic auth credentials in the Authorization header.
+ * @example
+ * const headers = generateHeaders('none', process.env);
+ * // headers will contain only the Content-Type header.
+ * @example
+ * const headers = generateHeaders('invalid_auth_type', process.env);
+ * // throws an error: Unsupported authentication type: invalid_auth_type
+ */
+
+module.exports = function buildK6Script(config) {
+  const { method, endpoints, endpoint, body, headers, options } = config;
+
+  // Ensure at least one of `endpoints` or `endpoint` is defined
+  if (!endpoints?.length && !endpoint) {
+    throw new Error(
+      'Either "endpoints" or "endpoint" must be defined in the configuration.'
+    );
+  }
+
+  // Get BASE_URL from environment variables
+  const BASE_URL = process.env.BASE_URL;
+  if (!BASE_URL) {
+    throw new Error("BASE_URL is not defined in the environment variables.");
+  }
+
+  // Resolve relative endpoints by prepending BASE_URL
+  const resolveEndpoint = (url) => {
+    return url.startsWith("/") ? `${BASE_URL}${url}` : url;
+  };
+
+  return `
+import http from 'k6/http';
+import { check } from 'k6';
+
+export const options = ${JSON.stringify(options, null, 2)};
+
+export default function () {
+  ${
+    endpoints?.length
+      ? endpoints
+          .map(
+            (url, i) => `
+    const resolvedUrl${i} = "${resolveEndpoint(url)}";
+    const res${i} = http.request("${method}", resolvedUrl${i}, ${
+              method === "GET" || method === "DELETE"
+                ? "null"
+                : JSON.stringify(body)
+            }, {
+      headers: ${JSON.stringify(headers, null, 2)}
+    });
+    console.log(\`Response Body for \${resolvedUrl${i}}: \${res${i}.body}\`);
+    check(res${i}, {
+      "status is 2xx": (r) => r.status >= 200 && r.status < 300
+    });
+  `
+          )
+          .join("\n")
+      : `
+    const resolvedUrl = "${resolveEndpoint(endpoint)}";
+\    const res = http.request("${method}", resolvedUrl, ${
+          method === "GET" || method === "DELETE"
+            ? "null"
+            : JSON.stringify(body)
+        }, {
+      headers: ${JSON.stringify(headers, null, 2)}
+    });
+    console.log(\`Response Body for \${resolvedUrl}: \${res.body}\`);
+    check(res, {
+      "status is 2xx": (r) => r.status >= 200 && r.status < 300
+    });
+  `
+  }
+}
+  `;
+};

package/libs/helpers/generateHeaders.js

@@ -0,0 +1,29 @@
+/**
+ * @module generateHeaders
+ * @description
+ * This module generates HTTP headers for API requests based on the specified authentication type.
+ * It supports API key, bearer token, basic authentication, and no authentication.
+ * Generates HTTP headers based on the specified authentication type.
+ * Supported auth types: api_key, bearer_token, basic, none.
+ */
+module.exports = function generateHeaders(authType, env) {
+  const headers = { "Content-Type": "application/json" };
+
+  if (authType === "api_key") {
+    headers["x-api-key"] = env.API_KEY || "";
+  } else if (authType === "bearer_token") {
+    headers["Authorization"] = `Bearer ${env.BEARER_TOKEN || ""}`;
+  } else if (authType === "basic") {
+    const base64 = Buffer.from(`${env.BASIC_USER}:${env.BASIC_PASS}`).toString(
+      "base64"
+    );
+    headers["Authorization"] = `Basic ${base64}`;
+  } else if (authType === "none") {
+    // No additional headers for "no auth"
+    // Default headers (e.g., Content-Type) are still included
+  } else {
+    throw new Error(`Unsupported authentication type: ${authType}`);
+  }
+
+  return headers;
+};

package/libs/helpers/resolveBody.js

@@ -0,0 +1,55 @@
+/**
+ * @module resolveBody
+ * @description
+ * This module resolves placeholders in a template string using environment variables,
+ * Faker templates, and JSON file includes.
+ * It supports the following types of placeholders:
+ * 1. Environment variables: {{username}} will be replaced with the value of process.env.username.
+ * 2. Faker templates: {{faker.internet.email}} will be replaced with a randomly generated email address.
+ * 3. JSON file includes: <address.json> will be replaced with the contents of the address.json file.
+ * */
+const fs = require("fs");
+const path = require("path");
+const faker = require("@faker-js/faker");
+
+module.exports = function resolveBody(template, env) {
+  let result = template;
+
+  // Replace env vars like {{username}}
+  result = result.replace(/{{(\w+)}}/g, (_, key) => {
+    if (!(key in env)) {
+      console.warn(`Missing environment variable for placeholder: {{${key}}}`);
+    }
+    return env[key] || "";
+  });
+
+  // Support faker templates like {{faker.internet.email}}
+  result = result.replace(/{{faker\.([\w.]+)}}/g, (_, methodPath) => {
+    const parts = methodPath.split(".");
+    let fn = faker;
+    for (const part of parts) {
+      fn = fn[part];
+      if (!fn) break;
+    }
+    if (typeof fn !== "function") {
+      throw new Error(`Invalid Faker template: {{faker.${methodPath}}}`);
+    }
+    return fn();
+  });
+
+  // Replace JSON file includes like <address.json>
+  result = result.replace(/<([\w.]+\.json)>/g, (_, fileName) => {
+    const filePath = path.join(__dirname, "../payloads", fileName);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Payload file not found: ${fileName}`);
+    }
+    return JSON.stringify(JSON.parse(fs.readFileSync(filePath, "utf-8")));
+  });
+
+  try {
+    return JSON.parse(result);
+  } catch (error) {
+    console.error("Failed to parse resolved body to JSON:", result);
+    throw new Error("Invalid JSON body after resolving placeholders.");
+  }
+};

package/libs/utils/k6Runner.js

@@ -0,0 +1,71 @@
+import fs from "fs";
+import path from "path";
+import { v4 as uuidv4 } from "uuid";
+import { spawn } from "child_process";
+
+/**
+ * Generates a temporary k6 script file.
+ * @param {string} scriptContent - The content of the k6 script.
+ * @param {string} scriptType - The type of script (default: "k6").
+ * @returns {string} - The path to the generated temporary script file.
+ */
+export function generateK6Script(scriptContent, scriptType = "k6") {
+  const tempFileName = `${scriptType}_script_${uuidv4()}.js`;
+  const tempFilePath = path.join(process.cwd(), "tmp", tempFileName);
+
+  // Ensure the directory exists and write the script content
+  fs.mkdirSync(path.dirname(tempFilePath), { recursive: true });
+  fs.writeFileSync(tempFilePath, scriptContent);
+  return tempFilePath;
+}
+
+/**
+ * Runs the k6 script using the `k6 run` command.
+ * @param {string} scriptPath - The path to the k6 script file.
+ * @returns {Promise<string>} - Resolves with the stdout of the k6 execution.
+ */
+
+export async function runK6Script(scriptPath) {
+  return new Promise((resolve, reject) => {
+    const k6Process = spawn("k6", ["run", scriptPath]);
+
+    let stdout = "";
+    let stderr = "";
+
+    // Capture stdout and log it in real-time
+    k6Process.stdout.on("data", (data) => {
+      stdout += data.toString();
+      console.log(data.toString()); // Log output in real-time
+    });
+
+    // Capture stderr and log it in real-time
+    k6Process.stderr.on("data", (data) => {
+      stderr += data.toString();
+      console.error(data.toString()); // Log errors in real-time
+    });
+
+    // Handle process exit
+    k6Process.on("close", (code) => {
+      // Always clean up temp file
+      fs.unlink(scriptPath, (unlinkErr) => {
+        if (unlinkErr) {
+          console.warn(`Failed to delete temp script: ${unlinkErr.message}`);
+        }
+      });
+
+      if (code !== 0) {
+        console.error("k6 run failed with code:", code);
+        console.error("stderr:", stderr);
+        reject(new Error(`k6 run failed with code ${code}: ${stderr}`));
+      } else {
+        resolve(stdout);
+      }
+    });
+
+    // Handle spawn errors
+    k6Process.on("error", (err) => {
+      console.error("Failed to start k6 process:", err.message);
+      reject(err);
+    });
+  });
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "k6-cucumber-steps",
+  "version": "1.0.0",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/qaPaschalE/k6-cucumber-steps.git"
+  },
+  "bugs": {
+    "url": "https://github.com/qaPaschalE/k6-cucumber-steps/issues"
+  },
+  "homepage": "https://github.com/qaPaschalE/k6-cucumber-steps#readme",
+  "scripts": {
+    "stress": "npx cucumber-js --format json:stress-results.json --tags @stress",
+    "stress:report": "cucumber-html-reporter --jsonFile=stress-results.json --output=stress-report.html",
+    "loadTest": "npx cucumber-js --format json:reports/load-results.json --tags @loadTest",
+    "load:report": "cucumber-html-reporter --jsonFile=load-results.json --output=load-report.html",
+    "test": "cucumber-js features/ --require-module @babel/register --require step_definitions/",
+    "build": "npm run clean && npm run compile",
+    "clean": "rm -rf dist/",
+    "compile": "babel src/ -d dist/"
+  },
+  "cucumber": {
+    "require": [
+      "step_definitions/**/*.js"
+    ]
+  },
+  "keywords": [
+    "k6",
+    "cucumber",
+    "bdd",
+    "performance-testing",
+    "api-testing",
+    "load-testing",
+    "stress-testing",
+    "steps",
+    "test-automation"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Enyimiri Chetachi Paschal",
+  "license": "ISC",
+  "description": "Cucumber step definitions for running k6 performance tests.",
+  "devDependencies": {
+    "@babel/cli": "^7.27.0",
+    "@babel/core": "^7.26.10",
+    "@babel/preset-env": "^7.26.9",
+    "@cucumber/cucumber": "^11.2.0",
+    "@faker-js/faker": "^9.7.0",
+    "@types/k6": "^1.0.2",
+    "child_process": "^1.0.2",
+    "cucumber-html-reporter": "^6.0.0",
+    "dotenv": "^16.5.0",
+    "esbuild": "^0.25.3",
+    "form-data": "^4.0.2",
+    "k6": "^0.0.0",
+    "tsconfig-paths": "^4.2.0"
+  }
+}