How to Use the Command 'tmt' (with Examples)

tmt (Test Management Tool) is a command-line utility designed to assist developers and testers in managing the lifecycle of tests. The tool provides extensive functionality to create, run, and debug tests while also providing the ability to manage test plans and stories. Its comprehensive features allow users to organize tests with great flexibility, making it a valuable asset in the continuous integration and testing workflows. Whether you’re setting up new test projects or managing existing ones, tmt streamlines the process with a variety of subcommands tailored to diverse test management needs.

Use case 1: List available tests, plans, and stories

Code:

tmt

Motivation:

At the beginning of a testing project, it is crucial to get a clear overview of all the available test resources such as tests, plans, and stories. This command provides a quick way to list everything that is available for you to work with, enabling you to plan your testing activities efficiently.

Explanation:

• tmt: By simply invoking the command without any additional parameters, the tool will list all tests, test plans, and associated stories available in the current project. This serves as a default information overview of the existing resources.

Example Output:

Available Tests:
- test-1
- test-2

Available Plans:
- plan-1

Available Stories:
- story-1

Use case 2: Initialize tmt files/project structure

Code:

tmt init

Motivation:

Initializing a project with the proper structure is a foundational step when starting with test management. tmt init automatically creates the necessary files and directories, setting up a workspace that is organized according to best practices. This ensures consistency and a ready-to-go environment for writing and managing tests.

Explanation:

• init: This subcommand instructs tmt to set up the initial infrastructure for your testing project. It creates configuration files (e.g., plans.yaml, tests.yaml) and directories that will be used to store test definitions, plans, and other related resources.

Example Output:

Initialized a new tmt project structure with:
created plan.yml
created tests directory

Use case 3: Create a new test with a template and a link

Code:

tmt test create --template beakerlib --link verifies:issue#1234

Motivation:

When adding new tests, it’s beneficial to start with a template that adheres to your organization’s standards. This command not only facilitates that but also automatically links the test to an issue or requirement, ensuring traceability between tests and the issues they address.

Explanation:

• test create: This command initiates the creation of a new test.
• --template beakerlib: Specifies that the test should use the ‘beakerlib’ template. Templates provide a pre-defined structure that ensures all necessary elements are included in your test script.
• --link verifies:issue#1234: Creates a link between the test and a specific issue (here, issue#1234). This is important for tracking what the test is designed to verify.

Example Output:

Test 'test-001' created with template 'beakerlib'.
Linked test to issue#1234.

Use case 4: List available tests, plans, or stories

Code:

tmt test|plan|story ls pattern

Motivation:

Sometimes a large project may contain numerous tests, plans, and stories, and it becomes necessary to filter or view specific ones based on certain patterns. This command allows for narrowed-down searches so that you can easily find what you are looking for.

Explanation:

• test|plan|story: Choose one of these options depending on whether you want to list tests, plans, or stories.
• ls: Stands for ’list’ and is used to output the available options that match a given pattern.
• pattern: The pattern is a string you provide that tmt uses to find matching tests, plans, or stories. This could be any part of a name or label applied to your resources.

Example Output:

Listing tests matching pattern 'regression':
- regression-test-1
- regression-test-2

Use case 5: Show detailed test metadata in the given context

Code:

tmt --context arch=aarch64 test show

Motivation:

Certain tests may behave differently based on context such as the environment they run in, specific configurations, or platforms like CPU architecture. This command retrieves detailed metadata for tests, giving insights into contextual dependencies or special settings that have been defined.

Explanation:

• --context arch=aarch64: Applies a context filter focusing on the specified architecture, ‘aarch64’ in this case. Context may consist of various configurations, but here it’s focusing on the CPU architecture.
• test show: Shows comprehensive metadata information about the tests, which allows you to understand how tests are set up in the given context, and any special instructions or conditions they might have.

Example Output:

Showing test metadata in context 'arch=aarch64':
- Test Name: Performance Test
- Dependencies: libarch64
- Environment Variables: VAR1=value1

Use case 6: Validate tmt files against the specification

Code:

tmt lint

Motivation:

Validating configuration and test files is essential to catch errors and maintain standards. tmt lint checks that all files related to tests and plans comply with the predefined specifications, preventing inconsistencies that could lead to test failures or incorrect test-bench setups.

Explanation:

• lint: This command reviews project files for any deviation from expected norms or syntax errors, issuing warnings or errors that need correction for your project files to be valid.

Example Output:

Files examined:
- tests.yaml: No issues found.
- plan.yaml: No issues found.
- story.yaml: Missing `summary` attribute.

Use case 7: Use filter

Code:

tmt tests ls --filter tag:foo --filter tier:0

Motivation:

In complex projects with many tests, it’s essential to apply filters to quickly find tests by their attributes such as tags or priority tiers. This usage of tmt allows for a streamlined search through potentially vast test resources, helping focus on what’s immediately relevant.

Explanation:

• tests ls: Lists available tests, fitting the criteria to be specified through filters.
• --filter tag:foo: Filters tests that have the ‘foo’ tag, helping sort tests by labels that are significant for the project.
• --filter tier:0: Further narrows down the tests to those having the tier level set to ‘0’, usually indicating prioritization or categorization for test execution.

Example Output:

Filtered tests:
- foo-tier0-test1
- foo-tier0-test2

Use case 8: Display help

Code:

tmt --help

Motivation:

Understanding how to use a tool’s functionality and its various options is critical, especially for new users or when encountering complex features. The help command provides a comprehensive reference of all possible commands and options available within tmt.

Explanation:

• --help: This option displays a help message on using the tmt command, including descriptions of all available subcommands and options in a user-friendly format.

Example Output:

Usage: tmt [OPTIONS] COMMAND [ARGS]...

Test Management Tool for creating, running, and debugging tests.

Options:
  --help  Show this message and exit.

Commands:
  init    Initialize tmt files/project structure.
  lint    Validate tmt files against the specification.
  ...

Conclusion:

The tmt command-line tool offers comprehensive capabilities for test management tasks such as creating, running, linking, and listing tests as well as organizing and validating project structures. Mastering its various features can significantly enhance the efficiency and accuracy of your test management workflow, helping align testing activities with project requirements and issues seamlessly.