wrk Load Test Tool Wrapper

Common errors

• Error: spawn wrk ENOENT

  cause The `wrk` command-line tool is not installed on the system or is not found in the system's PATH environment variable. The `node-wrk` package is just a wrapper and does not install the `wrk` binary itself.
  fix Ensure the `wrk` CLI tool is installed and accessible globally. For example, on macOS: `brew install wrk`. On Linux, you might need to compile it from source (refer to the official `wrk` GitHub page).

• ERR_REQUIRE_ESM: require() of ES Module ... is not supported.

  cause This error occurs when trying to use `require()` to import a package that is exclusively an ESM module. Although this package is CommonJS, this error might occur if `node-wrk` is integrated into a project that itself is configured as ESM-only and doesn't handle CJS interop correctly.
  fix While `node-wrk` is CJS, if your project is pure ESM, ensure Node.js is configured to allow CJS modules. Or, if you are mistakenly trying to import another ESM-only package with `require`, change it to `import`.

• TypeError: wrk is not a function

  cause This usually happens if the import statement is incorrect, such as `import { wrk } from 'wrk';` or `import * as wrk from 'wrk';` in an ESM context, where the package actually exports a default function.
  fix For CommonJS, use `const wrk = require('wrk');`. For ESM (via dynamic import), use `const { default: wrk } = await import('wrk');` to correctly access the default exported function.

Warnings

• breaking The `node-wrk` package is a wrapper for the external `wrk` command-line tool. The `wrk` CLI tool *must* be installed on your system and accessible via the system's PATH environment variable for this package to function. This is not an npm dependency.
  Fix: Install the `wrk` command-line tool according to its official documentation (e.g., `brew install wrk` on macOS, compile from source on Linux).
• gotcha The `node-wrk` package is no longer actively maintained. Its last publish was in September 2020. This means it may not receive updates for new Node.js versions, security vulnerabilities, or new features from the underlying `wrk` CLI tool.
  Fix: For critical applications, consider using `wrk` directly via `child_process` or exploring alternative, actively maintained Node.js load testing solutions.
• gotcha This package is CommonJS-only (`require`). It does not provide native ECMAScript Module (ESM) exports. Attempting a direct `import wrk from 'wrk'` will fail without specific build configurations or dynamic import (`await import('wrk')`).
  Fix: Use `const wrk = require('wrk');` in CommonJS environments. In ESM, use `const { default: wrk } = await import('wrk');`.
• gotcha The package does not ship with TypeScript type definitions, which can lead to a less type-safe development experience when used in TypeScript projects.
  Fix: Consider creating a declaration file (`wrk.d.ts`) with `declare module 'wrk';` or more specific type definitions for the `wrk` function and its `wrkResults` output structure.

Install

• npm install wrk npm
• yarn add wrk yarn
• pnpm add wrk pnpm

Imports

• wrk

  const wrk = require('wrk');

  The package is CommonJS-only and exports a single function as its default. This is the only supported import method.
• wrk
  wrong:

  import wrk from 'wrk';

  correct:

  const { default: wrk } = await import('wrk');

  While Node.js can sometimes import CommonJS modules via `import`, `node-wrk` does not provide an explicit ESM export. Direct `import wrk from 'wrk'` will likely fail. You must use dynamic `import` and access the `default` property.

Quickstart

This quickstart demonstrates how to use the `node-wrk` package to perform a series of load tests, incrementally increasing the number of concurrent connections. It shows how to configure `wrk` options, handle the callback, and accumulate results, providing a basic framework for performance analysis.

const wrk = require('wrk');

let conns = 1;
const results = [];

function benchmark() {
  if (conns === 100) {
    // In a real scenario, you'd process these results,
    // e.g., save to a file, aggregate, or display.
    console.log('--- Benchmark Complete ---');
    results.forEach((res, index) => {
      console.log(`
Test with ${res.connections} connections:`);
      console.log(`  Requests/Sec: ${res.requestsPerSec}`);
      console.log(`  Latency Avg: ${res.latencyAvg}`);
    });
    return;
  }
  
  console.log(`Running test with ${conns} connections...`);
  wrk({
    threads: 1,
    connections: conns,
    duration: '1s',
    printLatency: true,
    headers: { 'User-Agent': 'node-wrk-benchmark' },
    url: 'http://localhost:3000/' // Ensure a server is running here, e.g., 'python3 -m http.server 3000'
  }, function(err, out) {
     if (err) {
       console.error('wrk error:', err);
       // Often 'spawn wrk ENOENT' if the wrk CLI tool is not installed or in PATH
       return;
     }
     results.push(out);
     conns++;
     benchmark();
  });
}

// To run this example, ensure the `wrk` CLI tool is installed (e.g., `brew install wrk` on macOS)
// and a simple HTTP server is running on http://localhost:3000.
// You can start a simple Python server with: `python3 -m http.server 3000`

benchmark();