feat: implement traffic-weighted stress test framework and scenario improvements (#4169)

Signed-off-by: Logan Nguyen <[email protected]>

Author: quiet-node

.eslintrc.js

@@ -10,6 +10,9 @@ module.exports = {
         "plugin:@typescript-eslint/recommended",
         "prettier",
     ],
+    "globals": {
+        "__ENV": "readonly",
+    },
     "plugins": [
         "simple-import-sort",
         "header",

k6/.envexample

@@ -10,3 +10,4 @@ DEFAULT_GRACEFUL_STOP=
 FILTER_TEST=
 DEBUG_MODE=
 SIGNED_TXS=
+STRESS_TEST_TARGET_TOTAL_RPS=

k6/README.md

@@ -7,7 +7,9 @@
     "prep-and-run": "npm run prep && npm run k6",
     "prep": "env-cmd node src/prepare/prep.js",
     "k6": "env-cmd --use-shell k6 run src/scenarios/apis.js",
-    "k6-ws": "env-cmd --use-shell k6 run src/scenarios/ws-apis.js"
+    "k6-ws": "env-cmd --use-shell k6 run src/scenarios/ws-apis.js",
+    "stress-test": "TEST_TYPE=stress env-cmd --use-shell k6 run src/scenarios/stress-test.js",
+    "prep-and-stress": "npm run prep && npm run stress-test"
   },
   "dependencies": {
     "env-cmd": "^10.1.0",

k6/package.json

@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
+import { randomIntBetween } from 'https://jslib.k6.io/k6-utils/1.4.0/index.js';
 import { check, sleep } from 'k6';
 import { Gauge } from 'k6/metrics';
-import { randomIntBetween } from 'https://jslib.k6.io/k6-utils/1.4.0/index.js';
 
 import { setDefaultValuesForEnvParameters } from './parameters.js';
+import { calculateRateAllocation } from './traffic-weights.js';
 
 setDefaultValuesForEnvParameters();
 
@@ -178,20 +179,24 @@ function defaultMetrics() {
 }
 
 function getTestType() {
-  return __ENV.TEST_TYPE !== undefined && __ENV.TEST_TYPE === 'load' ? 'load' : 'performance';
+  if (__ENV.TEST_TYPE === 'stress') return 'stress';
+  if (__ENV.TEST_TYPE === 'load') return 'load';
+  return 'performance';
 }
 
 function markdownReport(data, isFirstColumnUrl, scenarios) {
+  const testType = getTestType();
   const firstColumnName = isFirstColumnUrl ? 'URL' : 'Scenario';
-  const header = `| ${firstColumnName} | VUS | Reqs | Pass % | RPS (1/s) | Pass RPS (1/s) | Avg. Req Duration (ms) | Median (ms) | Min (ms) | Max (ms) | P(90) (ms) | P(95) (ms) | Comment |
+  const secondColumnName = getTestType() === 'stress' ? 'Expected RPS' : 'VUS';
+  const header = `| ${firstColumnName} | ${secondColumnName} | Reqs | Pass % | RPS (1/s) | Pass RPS (1/s) | Avg. Req Duration (ms) | Median (ms) | Min (ms) | Max (ms) | P(90) (ms) | P(95) (ms) | Comment |
 |----------|-----|------|--------|-----|----------|-------------------|-------|-----|-----|-------|-------|---------|`;
 
   // collect the metrics
   const { metrics } = data;
 
   const isDebugMode = __ENV['DEBUG_MODE'] === 'true';
   if (isDebugMode) {
-    console.log("Raw metrics:");
+    console.log('Raw metrics:');
     console.log(JSON.stringify(metrics, null, 2));
   }
 
@@ -228,8 +233,12 @@ function markdownReport(data, isFirstColumnUrl, scenarios) {
   markdown += `JSON-RPC-RELAY URL:  ${__ENV['RELAY_BASE_URL']}\n\n`;
   markdown += `Timestamp: ${new Date(Date.now()).toISOString()} \n\n`;
   markdown += `Duration: ${__ENV['DEFAULT_DURATION']} \n\n`;
-  markdown += `Test Type: ${getTestType()} \n\n`;
-  markdown += `Virtual Users (VUs): ${__ENV['DEFAULT_VUS']} \n\n`;
+  markdown += `Test Type: ${testType} \n\n`;
+  if (testType === 'stress') {
+    markdown += `Target Total RPS: ${__ENV['STRESS_TEST_TARGET_TOTAL_RPS'] || 'N/A'} \n\n`;
+  } else {
+    markdown += `Virtual Users (VUs): ${__ENV['DEFAULT_VUS']} \n\n`;
+  }
 
   markdown += `${header}\n`;
   for (const scenario of Object.keys(scenarioMetrics).sort()) {
@@ -248,7 +257,16 @@ function markdownReport(data, isFirstColumnUrl, scenarios) {
       const httpMaxDuration = scenarioMetric['http_req_duration'].values['max'].toFixed(2);
 
       const firstColumn = isFirstColumnUrl ? scenarioUrls[scenario] : scenario;
-      markdown += `| ${firstColumn} | ${__ENV.DEFAULT_VUS} | ${httpReqs} | ${passPercentage} | ${rps} | ${passRps} | ${httpReqDuration} | ${httpMedDuration} | ${httpMinDuration} | ${httpMaxDuration} | ${httpP90Duration} | ${httpP95Duration} | |\n`;
+
+      if (testType === 'stress') {
+        // Show expected RPS for stress test
+        const expectedRPS = (globalThis.rateAllocation && globalThis.rateAllocation[scenario]) || 'N/A';
+        markdown += `| ${firstColumn} | ${expectedRPS} | ${httpReqs} | ${passPercentage} | ${rps} | ${passRps} | ${httpReqDuration} | ${httpMedDuration} | ${httpMinDuration} | ${httpMaxDuration} | ${httpP90Duration} | ${httpP95Duration} | |\n`;
+      } else {
+        // Show VUs for load/performance test
+        const actualVUs = (globalThis.vuAllocation && globalThis.vuAllocation[scenario]) || __ENV.DEFAULT_VUS;
+        markdown += `| ${firstColumn} | ${actualVUs} | ${httpReqs} | ${passPercentage} | ${rps} | ${passRps} | ${httpReqDuration} | ${httpMedDuration} | ${httpMinDuration} | ${httpMaxDuration} | ${httpP90Duration} | ${httpP95Duration} | |\n`;
+      }
     } catch (err) {
       console.error(`Unable to render report for scenario ${scenario}`);
     }
@@ -265,13 +283,12 @@ function TestScenarioBuilder() {
   this._testDuration = undefined;
   this._maxDuration = undefined;
 
-  this.build = function () {
-    const that = this;
+  this.build = () => {
     return {
-      options: getOptionsWithScenario(that._name, that._tags, that._maxDuration, that._testDuration),
-      run: function (testParameters, iteration = 0, vuIndex = 0, iterationByVu = 0) {
-        const response = that._request(testParameters, iteration, vuIndex, iterationByVu);
-        check(response, that._checks);
+      options: getOptionsWithScenario(this._name, this._tags, this._maxDuration, this._testDuration),
+      run: (testParameters, iteration = 0, vuIndex = 0, iterationByVu = 0) => {
+        const response = this._request(testParameters, iteration, vuIndex, iterationByVu);
+        check(response, this._checks);
         // if Load test, then we need to sleep for random time between 1 and 5 seconds
         if (getTestType() === 'load') {
           sleep(randomIntBetween(1, 5));
@@ -313,4 +330,94 @@ function TestScenarioBuilder() {
   return this;
 }
 
-export { getSequentialTestScenarios, markdownReport, TestScenarioBuilder };
+/**
+ * Get stress test scenario options for a specific endpoint
+ *
+ * Uses the "constant-arrival-rate" executor, which generates a fixed number of iterations (requests) per time unit.
+ * The executor will dynamically ramp up or lower the number of virtual users as needed to maintain the target request rate.
+ * This makes it ideal for stress and throughput testing where a steady RPS is required.
+ *
+ * See: https://grafana.com/docs/k6/latest/using-k6/scenarios/executors/constant-arrival-rate
+ *
+ * @param {string} endpoint - The endpoint name
+ * @param {number} targetTotalRPS - Target total RPS to distribute
+ * @param {string} duration - Test duration
+ * @returns {Object} K6 scenario configuration
+ */
+export function getStressScenarioOptions(endpoint, targetTotalRPS = 100, duration = '60s') {
+  const rateAllocation = calculateRateAllocation(targetTotalRPS);
+  const targetRate = rateAllocation[endpoint];
+  const VU_BUFFER_MULTIPLIER = parseFloat(__ENV.VU_BUFFER_MULTIPLIER) || 3; // default buffer multiplier
+
+  return {
+    executor: 'constant-arrival-rate',
+    rate: Math.max(1, Math.round(targetRate)), // requests per second (must be integer, minimum 1)
+    duration: duration,
+    preAllocatedVUs: Math.max(1, Math.ceil(targetRate * VU_BUFFER_MULTIPLIER)),
+    maxVUs: Math.max(1, Math.ceil(3 * targetRate * VU_BUFFER_MULTIPLIER)),
+    startTime: '0s', // All scenarios start simultaneously for stress testing
+    gracefulStop: __ENV.DEFAULT_GRACEFUL_STOP || '5s',
+    exec: 'run',
+  };
+}
+
+/**
+ * Create concurrent stress test scenarios with realistic traffic distribution
+ * @param {Object} tests - Test modules object
+ * @returns {Object} Stress test configuration
+ */
+function getStressTestScenarios(tests) {
+  tests = getFilteredTests(tests);
+
+  // Use new STRESS_TEST_TARGET_TOTAL_RPS environment variable
+  const targetTotalRPS = parseInt(__ENV.STRESS_TEST_TARGET_TOTAL_RPS) || 100;
+  const testDuration = __ENV.DEFAULT_DURATION || '60s';
+
+  const funcs = {};
+  const scenarios = {};
+  const thresholds = {};
+
+  // Create concurrent scenarios for all endpoints
+  for (const testName of Object.keys(tests).sort()) {
+    const testModule = tests[testName];
+    const testScenarios = testModule.options.scenarios;
+    const testThresholds = testModule.options.thresholds;
+
+    for (const [scenarioName] of Object.entries(testScenarios)) {
+      // Get stress scenario options with realistic RPS allocation
+      const stressOptions = getStressScenarioOptions(scenarioName, targetTotalRPS, testDuration);
+
+      funcs[scenarioName] = testModule[stressOptions.exec];
+      scenarios[scenarioName] = stressOptions;
+
+      // Set up thresholds
+      const tag = `scenario:${scenarioName}`;
+      for (const [name, threshold] of Object.entries(testThresholds)) {
+        if (name === 'http_req_duration') {
+          thresholds[`${name}{${tag},expected_response:true}`] = threshold;
+        } else {
+          thresholds[`${name}{${tag}}`] = threshold;
+        }
+      }
+      thresholds[`http_reqs{${tag}}`] = ['count>0'];
+      thresholds[`${SCENARIO_DURATION_METRIC_NAME}{${tag}}`] = ['value>0'];
+    }
+  }
+
+  const testOptions = Object.assign({}, getOptions(), { scenarios, thresholds });
+
+  return {
+    funcs,
+    options: testOptions,
+    scenarioDurationGauge: new Gauge(SCENARIO_DURATION_METRIC_NAME),
+  };
+}
+
+export {
+  getSequentialTestScenarios,
+  getStressTestScenarios,
+  markdownReport,
+  TestScenarioBuilder,
+  getFilteredTests,
+  getOptions,
+};

k6/src/lib/common.js

@@ -93,4 +93,5 @@ export const setDefaultValuesForEnvParameters = () => {
   __ENV['DEFAULT_LIMIT'] = __ENV['DEFAULT_LIMIT'] || 100;
   __ENV['DEFAULT_PASS_RATE'] = __ENV['DEFAULT_PASS_RATE'] || 0.95;
   __ENV['DEFAULT_MAX_DURATION'] = __ENV['DEFAULT_MAX_DURATION'] || 500;
+  __ENV['STRESS_TEST_TARGET_TOTAL_RPS'] = __ENV['STRESS_TEST_TARGET_TOTAL_RPS'] || 100;
 };

k6/src/lib/parameters.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Traffic weights from real production data (90 days: April 29 - July 29, 2025)
+ */
+export const trafficWeights = {
+  eth_getBlockByNumber: 0.687,
+  eth_getLogs: 0.13,
+  eth_chainId: 0.0594,
+  eth_blockNumber: 0.053,
+  eth_call: 0.0326,
+  eth_getBlockByHash: 0.0197,
+  eth_getTransactionReceipt: 0.0082,
+  eth_getBalance: 0.0064,
+  debug_traceBlockByNumber: 0.0048,
+  eth_syncing: 0.0032,
+  eth_gasPrice: 0.0029,
+  eth_sendRawTransaction: 0.0028,
+  eth_getTransactionCount: 0.0023,
+  net_version: 0.0011,
+  eth_getTransactionByHash: 0.0008,
+  eth_estimateGas: 0.0005,
+  eth_getFilterChanges: 0.0005,
+  eth_getCode: 0.0003,
+  debug_traceTransaction: 0.0002,
+  web3_clientVersion: 0.0002,
+  eth_getBlockReceipts: 0.0002,
+  eth_maxPriorityFeePerGas: 0.00012,
+  eth_getFilterLogs: 0.000063,
+  net_listening: 0.000058,
+  eth_feeHistory: 0.000049,
+  eth_getStorageAt: 0.000045,
+  eth_newFilter: 0.000021,
+  eth_uninstallFilter: 0.000008,
+  eth_submitHashrate: 0.000007,
+  eth_protocolVersion: 0.000006,
+  eth_newPendingTransactionFilter: 0.000005,
+  eth_hashrate: 0.000005,
+  eth_getTransactionByBlockHashAndIndex: 0.000005,
+  eth_signTransaction: 0.000004,
+  eth_getBlockTransactionCountByHash: 0.000004,
+  eth_coinbase: 0.000004,
+  eth_sign: 0.000004,
+  eth_getTransactionByBlockNumberAndIndex: 0.000003,
+  eth_getUncleByBlockNumberAndIndex: 0.000003,
+  eth_getUncleByBlockHashAndIndex: 0.000003,
+  eth_accounts: 0.000003,
+  eth_getBlockTransactionCountByNumber: 0.000003,
+  eth_mining: 0.000002,
+  eth_getUncleCountByBlockNumber: 0.000002,
+  eth_getUncleCountByBlockHash: 0.000002,
+  eth_submitWork: 0.000002,
+  eth_getWork: 0.000002,
+  eth_sendTransaction: 0.000002,
+  eth_newBlockFilter: 0.0000003,
+  eth_blobBaseFee: 0.00000001,
+  eth_getProof: 0.00000001,
+  net_peerCount: 0.000000003,
+  web3_sha3: 0.000000001,
+  eth_createAccessList: 0.00000001,
+};
+
+
+/**
+ * Calculate rate allocation based on traffic weights and total RPS
+ * @param {number} targetTotalRPS - Target total requests per second to distribute
+ * @returns {Object} RPS allocation per endpoint
+ */
+export function calculateRateAllocation(targetTotalRPS = 100) {
+  const allocation = {};
+
+  for (const [endpoint, weight] of Object.entries(trafficWeights)) {
+    // Direct proportional allocation: RPS = targetTotalRPS * percentage
+    const rps = weight * targetTotalRPS;
+    // Set minimum rate for very low-traffic endpoints and ensure it's an integer
+    // k6 requires rate to be an integer, so we round up to ensure at least 1 req/s for active endpoints
+    allocation[endpoint] = Math.max(1, Math.round(rps));
+  }
+
+  // Store allocation globally for reporting
+  globalThis.rateAllocation = allocation;
+
+  return allocation;
+}

k6/src/lib/traffic-weights.js

@@ -96,7 +96,7 @@ async function getSignedTxs(wallet, greeterContracts, gasPrice, gasLimit, chainI
     console.log('address: ', wallet.address);
 
     // amount to send (HBAR)
-    let amountInEther = '10';
+    let amountInEther = process.env.WALLET_BALANCE || '10';
     // Create transaction
     let tx = {
       to: wallet.address,

k6/src/prepare/prep.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import { textSummary } from 'https://jslib.k6.io/k6-summary/0.0.1/index.js';
+import exec from 'k6/execution';
+
+import { setupTestParameters } from '../lib/bootstrapEnvParameters.js';
+import { markdownReport } from '../lib/common.js';
+import { funcs, options, scenarioDurationGauge } from './stress/index.js';
+
+function handleSummary(data) {
+  return {
+    stdout: textSummary(data, { indent: ' ', enableColors: true }),
+    'stress-test-report.md': markdownReport(data, false, options.scenarios),
+  };
+}
+
+function run(testParameters) {
+  const scenario = exec.scenario;
+  funcs[scenario.name](testParameters, scenario.iterationInTest, exec.vu.idInInstance - 1, exec.vu.iterationInScenario);
+  scenarioDurationGauge.add(Date.now() - scenario.startTime, { scenario: scenario.name });
+}
+
+export { handleSummary, options, run };
+
+export const setup = setupTestParameters;