Set up k6 in the AppHost

Questi contenuti non sono ancora disponibili nella tua lingua.

⭐ Community Toolkit

This article is the reference for the Aspire k6 Hosting integration. It enumerates the AppHost APIs that you use to model a Grafana k6 performance and load-testing resource in your AppHost project.

Installation

To start building an Aspire app that uses k6, install the 📦 CommunityToolkit.Aspire.Hosting.k6 NuGet package:

aspire add k6

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

#:package CommunityToolkit.Aspire.Hosting.k6@*

<PackageReference Include="CommunityToolkit.Aspire.Hosting.k6" Version="*" />

aspire add k6

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the k6 hosting integration package:

{
  "packages": {
    "CommunityToolkit.Aspire.Hosting.k6": "*"
  }
}

The TypeScript AppHost bindings for k6 are provided by the Community Toolkit package. After installation, the .aspire/modules/aspire.mjs file in your project includes addK6 and related APIs.

Add k6 resource

Once you’ve installed the hosting integration in your AppHost project, you can add a k6 resource as shown in the following example:

var builder = DistributedApplication.CreateBuilder(args);

var myService = builder.AddProject<Projects.MyService>("myService");

var k6 = builder.AddK6("k6")
                .WithBindMount("scripts", "/scripts", isReadOnly: true)
                .WithScript("/scripts/main.js")
                .WithReference(myService)
                .WaitFor(myService);

// After adding all resources, run the app...
builder.Build().Run();

import { createBuilder } from "./.aspire/modules/aspire.mjs";

const builder = await createBuilder();

const myService = await builder.addProject("myService", "../MyService/MyService.csproj");

const k6 = await builder.addK6("k6");
await k6.withBindMount("scripts", "/scripts", { isReadOnly: true });
await k6.withScript("/scripts/main.js");
await k6.withReference(myService);
await k6.waitFor(myService);

// After adding all resources, run the app...

When Aspire adds a container image to the AppHost, as shown in the preceding example with the docker.io/grafana/k6 image, it creates a new k6 instance on your local machine.

Scripts configuration

You need to provide a JavaScript file for k6 to execute. Here is a minimal example:

import http from "k6/http";
import { sleep } from "k6";

export default function () {
    http.get(`${__ENV.services__myService__http__0}/hello`);

    sleep(1);
}

The services__myService__http__0 environment variable resolves to the http endpoint of the myService resource.

For more information on writing k6 scripts, see Write your first test with Grafana k6.

Customize ports

To use a fixed host port instead of a randomly assigned one, pass the port parameter to AddK6 or addK6:

var builder = DistributedApplication.CreateBuilder(args);

var myService = builder.AddProject<Projects.MyService>("myService");

var k6 = builder.AddK6("k6", port: 6565)
                .WithBindMount("scripts", "/scripts", isReadOnly: true)
                .WithScript("/scripts/main.js")
                .WithReference(myService)
                .WaitFor(myService);

// After adding all resources, run the app...
builder.Build().Run();

import { createBuilder } from "./.aspire/modules/aspire.mjs";

const builder = await createBuilder();

const myService = await builder.addProject("myService", "../MyService/MyService.csproj");

const k6 = await builder.addK6("k6", { port: 6565 });
await k6.withBindMount("scripts", "/scripts", { isReadOnly: true });
await k6.withScript("/scripts/main.js");
await k6.withReference(myService);
await k6.waitFor(myService);

// After adding all resources, run the app...

The port parameter sets the host port for the k6 HTTP API endpoint. When omitted, Aspire assigns a random port.

Enable browser extensions

To enable the k6 browser module — which adds browser-level APIs and frontend performance metrics to your k6 tests — pass enableBrowserExtensions: true to AddK6 or addK6:

var builder = DistributedApplication.CreateBuilder(args);

var myService = builder.AddProject<Projects.MyService>("myService");

var k6 = builder.AddK6("k6", enableBrowserExtensions: true)
                .WithBindMount("scripts", "/scripts", isReadOnly: true)
                .WithScript("/scripts/main.js")
                .WithReference(myService)
                .WaitFor(myService);

// After adding all resources, run the app...
builder.Build().Run();

import { createBuilder } from "./.aspire/modules/aspire.mjs";

const builder = await createBuilder();

const myService = await builder.addProject("myService", "../MyService/MyService.csproj");

const k6 = await builder.addK6("k6", { enableBrowserExtensions: true });
await k6.withBindMount("scripts", "/scripts", { isReadOnly: true });
await k6.withScript("/scripts/main.js");
await k6.withReference(myService);
await k6.waitFor(myService);

// After adding all resources, run the app...

For more information on the k6 browser module, see Using k6 browser.