k6pack

README

k6pack

TypeScript transpiler and module bundler for k6

The main goal of k6pack is to make TypeScript and modern JavaScript features available in k6 tests.

Features

• Supports TypeScript (.ts) and JavaScript (.js) input
• Supports remote (https) modules
• Single executable file, no external dependencies
• No Node.js installation required

Install

Precompiled binaries can be downloaded and installed from the Releases page.

If you have a go development environment, the installation can also be done with the following command:

go install github.com/grafana/k6pack/cmd/k6pack@latest

Usage

The name of the entry point must be specified as a parameter. The k6 compatible script is sent to the standard output, so it can be executed directly with k6.

k6pack script.ts | k6 run -

script.ts

import { User, newUser } from "./user";

export default () => {
  const user: User = newUser("John");
  console.log(user);
};

user.ts

interface User {
  name: string;
  id: number;
}

class UserAccount implements User {
  name: string;
  id: number;

  constructor(name: string) {
    this.name = name;
    this.id = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER);
  }
}

function newUser(name: string): User {
  return new UserAccount(name);
}

export { User, newUser };

CLI Reference

k6pack

TypeScript transpiler and module bundler for k6.

Synopsis

Bundle TypeScript/JavaScript sources into a single k6 test script.

sourcemap

Sourcemap is disabled by default. If sourcemap is enabled, the current directory will be set in the sourcemap as the source root directory. This can be changed by using the --source-root flag. You can even disable the source root setting by specifying the empty string.

k6pack [flags] filename

Flags

      --external stringArray   exclude module(s) from the bundle
  -h, --help                   help for k6pack
      --minify                 minify the output
  -o, --output string          write output to file (default stdout)
      --source-root string     sets the sourceRoot field in generated source maps (default "/home/iszkiba/work/toolbox/k6pack")
      --sourcemap              emit the source map with an inline data URL
      --timeout duration       HTTP timeout for remote modules (default 30s)
      --typescript             force TypeScript loader

How It Works

Under the hood, k6pack uses the esbuild library. A special esbuild plugin contains k6 specific configuration and another esbuild plugin implements loading from http/https URL.

k6pack can also be used as a go library.

Development

Tasks

This section contains a description of the tasks performed during development. If you have the xc (Markdown defined task runner) command-line tool, individual tasks can be executed simply by using the xc task-name command.

Click to expand

readme

Update documentation in README.md.

go run ./tools/gendoc README.md

lint

Run the static analyzer.

golangci-lint run

test

Run the tests.

go test -count 1 -race -coverprofile=build/coverage.txt ./...

coverage

View the test coverage report.

go tool cover -html=build/coverage.txt

build

Build the executable binary.

This is the easiest way to create an executable binary (although the release process uses the goreleaser tool to create release versions).

go build -ldflags="-w -s" -o build/k6pack ./cmd/k6pack

snapshot

Creating an executable binary with a snapshot version.

The goreleaser command-line tool is used during the release process. During development, it is advisable to create binaries with the same tool from time to time.

goreleaser build --snapshot --clean --single-target -o build/k6pack

examples

Run scripts from examples directory.

go run ./cmd/k6pack examples/script.ts | go run go.k6.io/k6@latest run -
go run ./cmd/k6pack examples/simple.ts | go run go.k6.io/k6@latest run -

clean

Delete the build directory.

rm -rf build

Documentation

Overview

Package k6pack contains a k6 TypeScript/JavaScript script packager.

Index

• type Metadata
  • func Pack(source string, opts *Options) ([]byte, *Metadata, error)
• type Options
• type PackError

Types

type Metadata

type Metadata struct {
	// Imports contains a list of k6 imports (core modules and extensions).
	Imports []string `json:"imports,omitempty"`
}

Metadata holds k6 related metadata, emitted under "k6" key of Metafile.

func Pack

func Pack(source string, opts *Options) ([]byte, *Metadata, error)

Pack transforms TypeScript/JavaScript sources into single k6 compatible JavaScript test script.

type Options

type Options struct {
	Directory  string
	Filename   string
	Timeout    time.Duration
	SourceMap  bool
	Minify     bool
	TypeScript bool
	Externals  []string
	SourceRoot string
}

Options used to specify transform/build options.

type PackError

type PackError = interface {
	error
	Format(width int, color bool) string
}

PackError is returned if any errors occur during transforming or bundling.