K6¶

Not available until the next release of testcontainers-go main

Introduction¶

The Testcontainers module for K6.

Using k6 extensions¶

This module takes advantage of k6x to dynamically build a k6 binary with all the k6 extensions required by the test script.

Adding this module to your project dependencies¶

Please run the following command to add the K6 module to your Go dependencies:

go get github.com/testcontainers/testcontainers-go/modules/k6

Usage example¶

Creating a K6 container

ctx := context.Background()

// create a container with the httpbin application that will be the target
// for the test script that runs in the k6 container
gcr := testcontainers.GenericContainerRequest{
    ProviderType: testcontainers.ProviderDocker,
    ContainerRequest: testcontainers.ContainerRequest{
        Image: "kennethreitz/httpbin",
        ExposedPorts: []string{
            "80",
        },
        WaitingFor: wait.ForExposedPort(),
    },
    Started: true,
}
httpbin, err := testcontainers.GenericContainer(ctx, gcr)
if err != nil {
    panic(fmt.Errorf("failed to create httpbin container %w", err))
}

defer func() {
    if err := httpbin.Terminate(ctx); err != nil {
        panic(fmt.Errorf("failed to terminate container: %w", err))
    }
}()

httpbinIP, err := httpbin.ContainerIP(ctx)
if err != nil {
    panic(fmt.Errorf("failed to get httpbin IP: %w", err))
}

absPath, err := filepath.Abs(filepath.Join("scripts", "httpbin.js"))
if err != nil {
    panic(fmt.Errorf("failed to get path to test script: %w", err))
}

// run the httpbin.js test scripts passing the IP address the httpbin container
k6, err := k6.RunContainer(
    ctx,
    k6.WithTestScript(absPath),
    k6.SetEnvVar("HTTPBIN", httpbinIP),
)
if err != nil {
    panic(fmt.Errorf("failed to start k6 container: %w", err))
}

defer func() {
    if err := k6.Terminate(ctx); err != nil {
        panic(fmt.Errorf("failed to terminate container: %w", err))
    }
}()

Module reference¶

The K6 module exposes one entrypoint function to run the K6 container, and this function receives two parameters:

func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*K6Container, error)

context.Context, the Go context.
testcontainers.ContainerCustomizer, a variadic argument for passing options.

Container Options¶

When starting the K6 container, you can pass options in a variadic way to configure it.

SetEnvVar¶

SetEnvVar sets an environment variable for the test script using the '--env' command-line flag in the k6 command in the container.

k6.RunContainer(ctx, k6.SetEnvVar("URL","test.k6.io"), k6.WithTestScript("/tests/test.js"))

WithCache¶

Use WithCache passes a volume to be used as a cache for building the k6 binary inside the k6 container. This option improves considerably the execution time of test suites that creates multiple k6 test containers. If the volume does not exits, it is created. The test is responsible for cleaning up this volume when no longer needed.

k6.RunContainer(ctx, WithCache("cache"), k6.WithTestScript("/tests/test.js"))

WithCmdOptions¶

Use WithCmdOptions to pass a variadic list of strings as options to the k6 run command

k6.RunContainer(ctx, WithCmdOptions("--vus=10", "--duration=30s"), k6.WithTestScript("/tests/test.js"))

WithTestScript¶

Use the WithTestScript option to specify the test script to run. The path to the script must be an absolute path. This option copies the script file to the container and pass it to k6's run command. At least one WithTestScript option must be specified.

k6.RunContainer(ctx, k6.WithTestScript("/tests/test.js"))