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, name=None, parent=None)

Guest provisioned for test execution

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

guest ...... hostname or ip address
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 (see the class attribute ‘_keys’ below).

ansible(playbook, extra_args=None)

Prepare guest using ansible playbook

details()

Show guest details such as distro and kernel

execute(command, **kwargs)

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.

load(data)

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.

pull(source=None, destination=None, options=None)

Pull files from the guest

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

push(source=None, destination=None, options=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=False)

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.

reconnect()

Ensure the connection to the guest is working after reboot

remove()

Remove the guest

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

classmethod requires()

No extra requires needed

save()

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()

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()

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()

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.Plan(node, run=None)

Plan object (L2 Metadata)

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

extra_L2_keys = ['context', 'environment', 'gate']
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)

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 ‘name’ should contain a unique test name.

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=None, name=None, workdir=None, context=None)

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)

User story object

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

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

show()

Show story details

property verified

Return links to relevant test coverage

class tmt.Test(data, name=None)

Test object (L1 Metadata)

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

Create a new test

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.

lint()

Check test against the L1 metadata specification.

Return whether the test is valid.

static overview(tree)

Show overview of available tests

show()

Show test details

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)

Search available plans

property root

Metadata root

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

Search available stories

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

Search available tests

property tree

Initialize tree only when accessed