Tagging missions and reports

Tags organize missions, select what the CLI runs, and filter uploaded reports. Tags are lowercase and may contain letters, numbers, hyphens, and underscores. Spaces are not allowed. A tag may contain up to 40 characters, and a mission may have up to 50 tags.

Add tags to a mission

Export the tags so the CLI can inspect them before running the mission, and pass the same value to runMissions:

import { runMissions } from 'testronaut';

export const tags = ['authentication', 'smoke'];

export async function executeMission() {
  return runMissions({
    mission: 'Log in and verify that the dashboard appears.',
    tags,
  }, 'login mission');
}

Tags apply to the main mission. Pre-mission and post-mission phases are not tagged and do not contribute to the run-level tag list.

Select missions from the CLI

The recommended syntax is a repeatable singular flag. It is explicit and avoids shell ambiguity around spaces:

testronaut --tag authentication --tag smoke
testronaut --tag untagged

The compact plural form remains supported:

testronaut --tags authentication,smoke
testronaut --tags "authentication, smoke"

If a comma-separated list contains spaces, quote the entire value. Without quotes, your shell splits it into separate arguments. Tags themselves cannot contain spaces.

Tag selection uses OR (any) matching by default. Use --tag-match all to require every selected tag:

testronaut --tag authentication --tag smoke --tag-match all

untagged is a reserved virtual filter and cannot be saved as a tag. When one or more mission filenames are provided explicitly, selection tags from both the CLI and configuration are ignored:

testronaut login.mission.js --tags checkout

The login mission still runs. Additive tags remain active.

Add tags for a run

Use the repeatable --add-tag form to add tags to every executed main mission:

testronaut --add-tag staging --add-tag full-test-run

The compact forms --add-tags staging,full-test-run and --add-tags "staging, full-test-run" are also supported. Config and CLI additions are combined and deduplicated.

testronaut-config.json

{
  "tags": ["smoke", "authentication"],
  "tagMatch": "any",
  "addTags": ["staging"]
}

CLI --tag/--tags and --tag-match override their configuration counterparts. --add-tag/--add-tags are additive with addTags from configuration.

Singular and plural flags may be repeated or combined. Values are normalized and deduplicated:

testronaut --tag smoke --tags authentication,smoke

Reports and Mission Control

The run-level tag list is the union of tags on all main missions. It appears at the top of a report and in the dashboard table. Select one or more tags to filter with any or all matching, or select untagged to find missions or runs without tags.

In Mission Control, dashboard tags can be combined with text search, status filters, and sorting. A run-level tag edit applies to every main mission in that uploaded report. Open a report to edit a single mission. These edits affect only the uploaded report snapshot and do not modify local mission files. See Use the Mission Control dashboard.