CLI tool and programmatic builder that enables k6 installation and test creation via npm packages
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.
- 🔧 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
.k6pathfile - 🎯 Test Factories: Pre-configured factories for common test types (load, smoke, spike, stress)
- 📊 Type Safety: Full TypeScript support with comprehensive type definitions
npm install k6-node --save-devOnce installed, you can run k6 commands directly through the package:
npx k6-node run script.jsThe tool will:
- Check for a custom k6 binary path in
.k6pathfile - Use an already installed binary if available
- Automatically download and install k6 binary if not found
- Execute your k6 command seamlessly
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');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'
});Create a .k6path file in your project root containing the path to your custom k6 binary:
/path/to/your/custom/k6
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"
}
}// 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: 'test@example.com'
}),
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'
}
});The package consists of two main components:
- CLI Tool: Handles k6 binary management and execution
- Programmatic Builder: Provides a fluent API for creating k6 tests in TypeScript/JavaScript
This package will continue to evolve with additional test factories, enhanced reporting integration, and extended k6 feature support.
MIT