Classes

Class Structure

Here’s the overview of core classes:

Common
├── Tree
├── Core
│   ├── Plan
│   ├── Story
│   └── Test
├── Step
│   ├── Discover
│   ├── Execute
│   ├── Finish
│   ├── Prepare
│   ├── Provision
│   └── Report
├── Plugin
│   ├── DiscoverPlugin
│   │   ├── DiscoverFmf
│   │   └── DiscoverShell
│   ├── ExecutePlugin
│   │   ├── ExecuteDetach
│   │   └── ExecuteInternal
│   ├── FinishPlugin
│   │   └── FinishShell
│   ├── PreparePlugin
│   │   ├── PrepareAnsible
│   │   ├── PrepareInstall
│   │   └── PrepareShell
│   ├── ProvisionPlugin
│   │   ├── ProvisionConnect
│   │   ├── ProvisionLocal
│   │   ├── ProvisionMinute
│   │   ├── ProvisionPodman
│   │   └── ProvisionTestcloud
│   └── ReportPlugin
│       ├── ReportDisplay
│       └── ReportHtml
├── Guest
│   ├── GuestContainer
│   ├── GuestLocal
│   ├── GuestMinute
│   └── GuestTestcloud
├── Run
├── Status
└── Clean

Attributes

Object hierarchy is following: Run -> Plans -> Steps -> Plugins, where the Run is on the top of this hierarchy. The objects have the parent attribute, that is pointing to the parent in which the current instance is contained.

The node attribute of Test, Plan and Story instances references the original leaf node of the fmf metadata tree from which the respective test, plan or story have been created.

In a similar way, the tree property of the Tree instance points to the original fmf.Tree from which it was initialized.

Essential Classes

Test Management Tool

class tmt.Clean(parent=None, name=None, workdir=None, context=None)

A class for cleaning up workdirs, guests or images

guests()

Clean guests of runs

images()

Clean images of provision plugins

runs()

Clean workdirs of runs

class tmt.Guest(data: GuestData, name: Optional[str] = None, parent: Optional[Common] = None)

Guest provisioned for test execution

A base class for guest-like classes. Provides some of the basic methods and functionality, but note some of the methods are left intentionally empty. These do not have valid implementation on this level, and it’s up to Guest subclasses to provide one working in their respective infrastructure.

The following keys are expected in the ‘data’ container:

role ....... guest role in the multihost scenario
guest ...... name, hostname or ip address

These are by default imported into instance attributes.

ansible(playbook: str, extra_args: Optional[str] = None) None

Prepare guest using ansible playbook

details() None

Show guest details such as distro and kernel

execute(command: Union[str, List[str]], **kwargs: Any) CommandOutput

Execute command on the guest

command … string or list of command arguments (required) env ……. dictionary with environment variables cwd ……. working directory to be entered before execution

If the command is provided as a list, it will be space-joined. If necessary, quote escaping has to be handled by the caller.

guest: Optional[str]
load(data: GuestData) None

Load guest data into object attributes for easy access

Called during guest object initialization. Takes care of storing all supported keys (see class attribute _keys for the list) from provided data to the guest object attributes. Child classes can extend it to make additional guest attributes easily available.

Data dictionary can contain guest information from both command line options / L2 metadata / user configuration and wake up data stored by the save() method below.

localhost = False
pull(source: Optional[str] = None, destination: Optional[str] = None, options: Optional[List[str]] = None, extend_options: Optional[List[str]] = None) None

Pull files from the guest

push(source: Optional[str] = None, destination: Optional[str] = None, options: Optional[List[str]] = None) None

Push files to the guest

reboot(hard: bool = False, command: Optional[str] = None, timeout: Optional[int] = None) bool

Reboot the guest, return True if successful

Parameter ‘hard’ set to True means that guest should be rebooted by way which is not clean in sense that data can be lost. When set to False reboot should be done gracefully.

Use the ‘command’ parameter to specify a custom reboot command instead of the default ‘reboot’.

Parameter ‘timeout’ can be used to specify time (in seconds) to wait for the guest to come back up after rebooting.

reconnect(timeout: Optional[int] = None, tick: float = 5, tick_increase: float = 1.0) bool

Ensure the connection to the guest is working

The default timeout is 5 minutes. Custom number of seconds can be provided in the timeout parameter. This may be useful when long operations (such as system upgrade) are performed.

remove() None

Remove the guest

Completely remove all guest instance data so that it does not consume any disk resources.

classmethod requires() List[str]

No extra requires needed

role: Optional[str]
save() GuestData

Save guest data for future wake up

Export all essential guest data into a dictionary which will be stored in the guests.yaml file for possible future wake up of the guest. Everything needed to attach to a running instance should be added into the data dictionary by child classes.

start() None

Start the guest

Get a new guest instance running. This should include preparing any configuration necessary to get it started. Called after load() is completed so all guest data should be available.

stop() None

Stop the guest

Shut down a running guest instance so that it does not consume any memory or cpu resources. If needed, perform any actions necessary to store the instance status to disk.

wake() None

Wake up the guest

Perform any actions necessary after step wake up to be able to attach to a running guest instance and execute commands. Called after load() is completed so all guest data should be prepared.

class tmt.GuestSsh(data: GuestData, name: Optional[str] = None, parent: Optional[Common] = None)

Guest provisioned for test execution, capable of accepting SSH connections

The following keys are expected in the ‘data’ dictionary:

role ....... guest role in the multihost scenario (inherited)
guest ...... hostname or ip address (inherited)
port ....... port to connect to
user ....... user name to log in
key ........ path to the private key (str or list)
password ... password

These are by default imported into instance attributes.

ansible(playbook: str, extra_args: Optional[str] = None) None

Prepare guest using ansible playbook

execute(command: Union[str, List[str]], **kwargs: Any) CommandOutput

Execute command on the guest

command … string or list of command arguments (required) env ……. dictionary with environment variables cwd ……. working directory to be entered before execution

If the command is provided as a list, it will be space-joined. If necessary, quote escaping has to be handled by the caller.

key: List[str]
password: Optional[str]
port: Optional[int]
pull(source: Optional[str] = None, destination: Optional[str] = None, options: Optional[List[str]] = None, extend_options: Optional[List[str]] = None) None

Pull files from the guest

push(source: Optional[str] = None, destination: Optional[str] = None, options: Optional[List[str]] = None) None

Push files to the guest

By default the whole plan workdir is synced to the same location on the guest. Use the ‘source’ and ‘destination’ to sync custom location and the ‘options’ parametr to modify default options which are ‘-Rrz –links –safe-links –delete’.

reboot(hard: bool = False, command: Optional[str] = None, timeout: Optional[int] = None, tick: float = 30.0, tick_increase: float = 1.0) bool

Reboot the guest, return True if reconnect was successful

Parameter ‘hard’ set to True means that guest should be rebooted by way which is not clean in sense that data can be lost. When set to False reboot should be done gracefully.

Use the ‘command’ parameter to specify a custom reboot command instead of the default ‘reboot’.

remove() None

Remove the guest

Completely remove all guest instance data so that it does not consume any disk resources.

classmethod requires() List[str]

No extra requires needed

stop() None

Stop the guest

Shut down a running guest instance so that it does not consume any memory or cpu resources. If needed, perform any actions necessary to store the instance status to disk.

user: Optional[str]
class tmt.Plan(*, node: Tree, run: Optional[Run] = None, skip_validation: bool = False, raise_on_validation_error: bool = False, **kwargs: Any)

Plan object (L2 Metadata)

context: Dict[str, List[str]] = {}
static create(name, template, path, force=False, dry=None)

Create a new plan

static edit_template(content)

Edit the default template with custom values

property environment

Return combined environment from plan data and command line

export(format_='yaml')

Export plan data into requested format

Supported formats are ‘yaml’ and ‘dict’.

extra_L2_keys = ['context', 'environment', 'environment-file', 'gate']
gate: List[str] = []
go()

Execute the plan

lint()

Check plan against the L2 metadata specification

Return whether the plan is valid.

static overview(tree)

Show overview of available plans

show()

Show plan details

steps(enabled=True, disabled=False, names=False, skip=None)

Iterate over enabled / all steps

Yields instances of all enabled steps by default. Use ‘names’ to yield step names only and ‘disabled=True’ to iterate over all. Use ‘skip’ to pass the list of steps to be skipped.

class tmt.Result(data, name=None, test=None)

Test result

The following keys are expected in the ‘data’ dictionary:

result ........... test execution result
log .............. one or more log files
note ............. additional result details
duration ......... test execution time (hh:mm:ss)

Required parameter ‘test’ or ‘name’ should contain a test reference.

export()

Save result data for future wake-up

show()

Return a nicely colored result with test name (and note)

static summary(results)

Prepare a nice human summary of provided results

static total(results)

Return dictionary with total stats for given results

class tmt.Run(id_=None, tree=None, context=None)

Test run, a container of plans

property environment

Return environment combined from wake up and command line

finish()

Check overall results, return appropriate exit code

follow()

Periodically check for new lines in the log.

go()

Go and do test steps for selected plans

load()

Load list of selected plans and enabled steps

load_from_workdir()

Load the run from its workdir, do not require the root in run.yaml to exist. Doest not load the fmf tree.

Use only when the data in workdir is sufficient (e.g. tmt clean and status only require the steps to be loaded and their status).

property plans

Test plans for execution

save()

Save list of selected plans and enabled steps

class tmt.Status(parent: Optional[CommonDerivedType] = None, name: Optional[str] = None, workdir: Optional[Union[typing_extensions.Literal[True], str]] = None, context: Optional[Context] = None, relative_indent: int = 1, **kwargs: Any)

Status of tmt work directories.

FIRST_COL_LEN = 11
LONGEST_STEP = 'provision'
static colorize_column(content)

Add color to a status column

static get_overall_plan_status(plan)

Examines the plan status (find the last done step)

classmethod pad_with_spaces(string)

Append spaces to string to properly align the first column

plan_matches_filters(plan)

Check if the given plan matches filters from the command line

print_header()

Print the header of the status table based on verbosity

print_plans_status(run)

Display the status of each plan of the given run

print_run_status(run)

Display the overall status of the run

print_verbose_status(run)

Display the status of each step of the given run

process_run(run)

Display the status of the given run based on verbosity

run_matches_filters(run)

Check if the given run matches filters from the command line

show()

Display the current status

class tmt.Story(*, node: Tree, skip_validation: bool = False, raise_on_validation_error: bool = False, **kwargs: Any)

User story object

KEYS_SHOW_ORDER: List[str] = ['summary', 'title', 'story', 'id', 'priority', 'description', 'example', 'enabled', 'order', 'tag', 'tier', 'link']
coverage(code, test, docs)

Show story coverage

static create(name, template, path, force=False, dry=None)

Create a new story

property documented

Return links to relevant documentation

example: List[str] = []
export(format_='rst', title=True)

Export story data into requested format

property implemented

Return links to relevant source code

lint()

Check story against the L3 metadata specification.

Return whether the story is valid.

static overview(tree)

Show overview of available stories

priority: Optional[StoryPriority] = None
show()

Show story details

story: str
title: Optional[str] = None
property verified

Return links to relevant test coverage

class tmt.Test(*, node: Tree, skip_validation: bool = False, raise_on_validation_error: bool = False, **kwargs: Any)

Test object (L1 Metadata)

KEYS_SHOW_ORDER: List[str] = ['summary', 'description', 'contact', 'component', 'id', 'test', 'path', 'framework', 'manual', 'require', 'recommend', 'environment', 'duration', 'enabled', 'order', 'result', 'tag', 'tier', 'link']
component: List[str] = []
contact: List[str] = []
static create(name, template, path, force=False, dry=None)

Create a new test

duration: Optional[str] = '5m'
environment: Optional[Dict[str, str]] = {}
export(format_='yaml', keys=None)

Export test data into requested format

In addition to ‘yaml’ and ‘dict’ it supports also a special format ‘execute’ used by the execute step which returns (test-name, test-data) tuples.

framework: Optional[str] = None
classmethod from_dict(mapping: Dict[str, Any], name: str, skip_validation: bool = False, raise_on_validation_error: bool = False, **kwargs: Any) Test

Initialize test data from a dictionary.

Useful when data describing a test are stored in a mapping instead of an fmf node.

lint()

Check test against the L1 metadata specification.

Return whether the test is valid.

manual: bool = False
static overview(tree)

Show overview of available tests

path: Optional[str] = None
recommend: List[str] = []
require: List[Union[str, FmfId]] = []
result: str = 'respect'
show()

Show test details

test: str
class tmt.Tree(path='.', tree=None, context=None)

Test Metadata Tree

static init(path, template, force, **kwargs)

Initialize a new tmt tree, optionally with a template

plans(keys=None, names=None, filters=None, conditions=None, run=None, links=None, excludes=None)

Search available plans

property root

Metadata root

stories(keys=None, names=None, filters=None, conditions=None, whole=False, links=None, excludes=None)

Search available stories

tests(keys=None, names=None, filters=None, conditions=None, unique=True, links=None, excludes=None)

Search available tests

property tree

Initialize tree only when accessed