k6-core

Playwright-style testing framework for k6 with TypeScript

A fully type-safe, beginner-friendly testing framework that brings Playwright's ergonomics to k6 performance and API testing.

Features

• 🎭 Playwright-like API - Familiar syntax for k6 users
• 🔒 Fully Type-Safe - TypeScript-first with type-only API schemas
• ⚡ Synchronous - Pure k6 execution, no async/await
• 🧩 Extensible - Fixture system with test.extend()
• 🎯 Simple - Low-magic, deterministic, easy to understand

Quick Start

npm init k6-core
cd my-k6-project
npm install
npm test

Project Structure

k6-core-project/
├─ k6.config.ts          # Configuration (Playwright-style)
├─ package.json
├─ tsconfig.json
├─ .github/workflows/    # CI templates
├─ .gitlab-ci.yml
└─ src/
   ├─ api/              # Type-only API schemas
   ├─ tests/            # Test files
   ├─ setup/            # Setup/teardown scripts
   └─ fixtures/         # Custom fixtures

Usage

Define API Schema (Type-Only)

// src/api/api.types.ts
export type API = [
  {
    method: 'GET';
    url: '/users';
    params?: { page?: number };
    response: { id: number; name: string }[];
  },
  {
    method: 'POST';
    url: '/users';
    params: { name: string };
    response: { id: number };
  },
];

Write Tests

// src/tests/users.spec.ts
import { test } from 'k6-core';
import type { API } from '../api/api.types.js';
import { createRequest } from 'k6-core';

const typedTest = test.extend<{
  request: import('k6-core').RequestClient<API>;
}>({
  request: ({}, use) => {
    use(createRequest<API>('https://api.example.com'));
  },
});

test('get users', ({ request }) => {
  const res = request.get('/users');
  res.expect().toHaveStatus(200);
  res.expect().toHaveValidJson();
});

test('post user', ({ request }) => {
  const res = request.post('/users', {
    body: { name: 'John' },
  });
  res.expect().toHaveStatus(201);
});

test('custom VUs', ({ request }, use) => {
  use({ vus: 2000, duration: '2m' });
  
  const res = request.get('/users');
  res.expect().toHaveStatus(200);
});

Configuration

// k6.config.ts
import { defineConfig } from 'k6-core';

export default defineConfig({
  baseURL: 'https://api.example.com',
  
  globalSetup: 'src/setup/global-setup.ts',
  globalTeardown: 'src/setup/global-teardown.ts',
  
  projects: [
    {
      name: 'smoke',
      testDir: 'src/tests/users.spec.ts',
      setup: 'src/setup/smoke.setup.ts',
      use: {
        vus: 1,
        duration: '30s',
      },
    },
    {
      name: 'load',
      testDir: 'src/tests',
      use: {
        vus: 50,
        duration: '2m',
      },
    },
  ],
});

CLI

# Run all tests
k6-core run

# Run specific project
k6-core run --project smoke

# Filter tests
k6-core run --grep "users"

# Debug mode
k6-core run --debug

Assertions

All assertions map to k6 checks and metrics:

res.expect().toHaveStatus(200);
res.expect().toHaveValidJson();
res.expect().toHaveJsonProperty('0.id');
res.expect().toHaveHeader('content-type');
res.expect().toHaveResponseTimeLessThan(300);

Hooks

test.beforeAll(() => {
  // Runs once before all tests
});

test.afterAll(() => {
  // Runs once after all tests
});

test.beforeEach(() => {
  // Runs before each test
});

test.afterEach(() => {
  // Runs after each test
});

License

MIT