Filter k6 tests by tag

Run a subset of a k6 load test by filtering on request-level or group-level tags defined in your script.

k6 tags are short labels you add to requests and groups in your script. This filter saves time by running only the tagged subset of requests you care about, instead of the full script every time.

To add organizational tags to a load test or run in BrowserStack instead, see Add tags.

Prerequisites

Before you start, confirm the following:

• Your k6 script has tags at the request level, group level, or both. If not, you are ready to add them.
• You have an active BrowserStack Load Testing account.
• You can access the BrowserStack Load Testing dashboard, or the BrowserStack CLI if you prefer YAML-driven runs.

Where k6 tags come from

A k6 script can have tags at two levels that this filter recognizes.

Request-level tags

Request-level tags are added inside params.tags on any http.* call, such as http.get or http.post. They label individual HTTP requests so you can target them by name.

http.get("https://example.com/", { tags: { name: "01_Homepage_Get" } });

The name tag is the standard way to label a request in k6, but the filter matches any value in params.tags. For example, a request tagged { name: "Login_Get", category: "smoke" } matches a filter for either Login_Get or smoke.

Group-level tags

Group-level tags come from the name you pass to group("name", () => { ... }). They label a block of requests as a logical unit, such as a checkout flow or an API workflow. When groups are nested, their names join with :: to form a path.

group("ABC", () => {
  group("heavy", () => {
    http.get("https://example.com/api/products");
  });
});

In this example, the inner http.get lives at the group path ABC::heavy.

When you set up a filter, BrowserStack skips every request whose tags do not match. Skipped requests are not sent over the network, do not record any metrics, and do not appear in the report.

How matching works

Filter matches are exact. Use the exact string from your script when you enter a filter value. The filter does not remove @ prefixes, ignore upper or lower case, or split values on spaces.

If you set filters at both levels, BrowserStack uses OR to combine them. In include mode, a request runs when a match is found at any level you set.

Common group path typos

You do not need to worry about small typos in group paths. The filter cleans these up before matching:

• Extra :: at the start or end. For example, ::checkout::payment:: becomes checkout::payment.
• Three or more colons in a row. For example, checkout::::payment becomes checkout::payment.
• Extra spaces around segments. For example, checkout :: payment becomes checkout::payment.

A filter that has no real segments, such as just "::", is not allowed.

Configure the filter

Choose include mode to run only the matching tests, or exclude mode to run everything except the matching tests. You can use only one mode per run.

Depending on your preferred method, select any one of the following to configure the filter:

browserstack-load run --config browserstack-load.yml

Example script and filter outcomes

The following k6 script defines requests at multiple group levels:

With this script, different filters run the following requests:

What happens when you run the test

When the load test runs:

• Every matching request runs normally, with the same metrics, dashboard rows, and response data as a non-filtered run.
• Every non-matching request is skipped before it is sent. No HTTP traffic is generated, no request count or duration metrics are recorded, and no rows appear in the report.
• The k6 iteration loop, scenarios, ramp-up, and virtual user (VU) pacing all work the same as a non-filtered run. Only individual requests are skipped.

Limitations

• Skipped requests leave no trace: Skipped requests do not appear in dashboards, exports, or downloaded reports. It is as if the script never reached that line.
• Other code still runs: Only http.* calls are skipped. Any other JavaScript in the iteration still runs, including sleep calls, calculations, and console.log statements.
• Tag limits: Each tag can be up to 64 characters long. Allowed characters are letters, numbers, underscores (_), hyphens (-), periods (.), colons (:), the at symbol (@), forward slashes (/), and spaces. The slash and space let you use HTTP-route-style tags like GET /api/users. You can add up to 50 tags per level for each run.

Related topics

• Configure load parameters - Overview of all available load configuration options.
• Configure multiple scenarios - Run multiple test scenarios in a single load test.
• Add tags - Attach organizational labels to load tests and runs for dashboard filtering.