Overview

A comprehensive Node.js solution that bridges the gap in the k6 ecosystem: k6 currently doesn't support installation via npm packages. This package provides both a CLI tool and a powerful programmatic builder to define k6 as a dependency in your project and automatically handles the binary installation process.

Features

• 🔧 Automatic Binary Management: Downloads and installs the appropriate k6 binary for Windows, Linux, and macOS
• 🧩 Programmatic Test Builder: Create k6 tests using a fluent, type-safe TypeScript API
• 📦 NPM Integration: Use k6 as a proper npm dependency in your projects
• ⚙️ Custom Binary Support: Configure custom k6 binary paths via .k6path file
• 🎯 Test Factories: Pre-configured factories for common test types (load, smoke, spike, stress)
• 📊 Type Safety: Full TypeScript support with comprehensive type definitions

Related Documentation

• k6 Official Documentation
• k6 JavaScript API
• k6 Installation Guide
• k6 Testing Guides

Installation

npm install k6-node --save-dev

Usage

CLI Usage

Once installed, you can run k6 commands directly through the package:

npx k6-node run script.js

The tool will:

1. Check for a custom k6 binary path in .k6path file
2. Use an already installed binary if available
3. Automatically download and install k6 binary if not found
4. Execute your k6 command seamlessly

Programmatic Builder Usage

Create sophisticated k6 tests programmatically using the builder pattern:

import { K6TestBuilder, k6GET, statusCheck } from 'k6-node';

const test = new K6TestBuilder()
  .addImports("import { htmlReport } from 'https://raw.githubusercontent.com/benc-uk/k6-reporter/main/dist/bundle.js'")
  .setOptions({
    stages: [
      { duration: '2m', target: 100 },    // Ramp-up to 100 users
      { duration: '5m', target: 100 },    // Stay at 100 users
      { duration: '1m', target: 0 }       // Ramp-down to 0
    ],
    thresholds: {
      'http_req_duration': ['p(95)<500', 'p(99)<1000'],
      'http_req_failed': ['rate<0.01']
    }
  })
  .createScenario('main_scenario', [
    {
      name: 'Get homepage',
      request: k6GET('https://test-api.k6.io/public/crocodiles/'),
      checks: [statusCheck(200)],
      sleep: '1s'
    }
  ])
  .setRawSetupCode(`
    console.log('Test setup completed');
    return { timestamp: new Date().toISOString() };
  `)
  .setRawTeardownCode(`
    console.log('Test teardown completed');
    console.log('Setup data:', JSON.stringify(data));
  `);

// Run the test
await test.run({
  output: 'json=results.json',
  verbose: true
});

// Or save the script for later use
test.saveScript('load-test.js');

Test Factories

Use pre-configured factories for common test patterns:

import { createK6LoadTest, createK6SmokeTest, k6GET, statusCheck } from 'k6-node';

// Load Test
const loadTest = createK6LoadTest({
  stages: [
    { duration: '5m', target: 100 },
    { duration: '10m', target: 100 },
    { duration: '5m', target: 0 }
  ],
  steps: [
    {
      request: k6GET('https://api.example.com/users'),
      checks: [statusCheck(200)]
    }
  ],
  thresholds: {
    'http_req_duration': ['p(95)<500']
  }
});

// Smoke Test
const smokeTest = createK6SmokeTest({
  steps: [
    {
      request: k6GET('https://api.example.com/health'),
      checks: [statusCheck(200)]
    }
  ],
  vus: 1,
  duration: '1m'
});

Custom Binary Path

Create a .k6path file in your project root containing the path to your custom k6 binary:

/path/to/your/custom/k6

Project Integration

Add k6 as a development dependency in your package.json:

{
  "devDependencies": {
    "k6-node": "^1.0.0"
  },
  "scripts": {
    "test:load": "k6-node run tests/load.js",
    "test:smoke": "k6-node run tests/smoke.js",
    "test:build": "node build-test.js"
  }
}

Example: Complete Load Test

// load-test.ts
import { createK6LoadTest, k6GET, k6POST, statusCheck, responseTimeCheck } from 'k6-node';

const test = createK6LoadTest({
  stages: [
    { duration: '2m', target: 50 },
    { duration: '3m', target: 100 },
    { duration: '2m', target: 50 },
    { duration: '1m', target: 0 }
  ],
  steps: [
    {
      name: 'Get users list',
      request: k6GET('https://api.example.com/users'),
      checks: [
        statusCheck(200),
        responseTimeCheck(1000)
      ],
      sleep: '1s'
    },
    {
      name: 'Create new user',
      request: k6POST('https://api.example.com/users', {
        name: 'Test User',
        email: '[email protected]'
      }),
      checks: [
        statusCheck(201),
        responseTimeCheck(2000)
      ]
    }
  ],
  thresholds: {
    'http_req_duration': ['p(95)<800', 'p(99)<1500'],
    'http_req_failed': ['rate<0.05'],
    'checks': ['rate>0.95']
  },
  imports: [
    "import { Trend, Counter } from 'k6/metrics';"
  ]
});

// Run with detailed output
test.run({
  output: 'json=results.json',
  verbose: true,
  environment: {
    K6_WEB_DASHBOARD: 'true'
  }
});

Architecture

The package consists of two main components:

1. CLI Tool: Handles k6 binary management and execution
2. Programmatic Builder: Provides a fluent API for creating k6 tests in TypeScript/JavaScript

Future Development

This package will continue to evolve with additional test factories, enhanced reporting integration, and extended k6 feature support.

License

MIT