tmt.base package

Submodules

tmt.base.core module

Base Metadata Classes

Bases: Common

A class for cleaning up workdirs, guests or images

Initialize name and relation with the parent object

Always skip to initialize the work tree.

cli_invocation: 'tmt.cli.CliInvocation' | None = None

guests(run_ids: tuple[str, ...], keep: int | None) → bool: Clean guests of runs

images() → bool: Clean images of provision plugins

runs(id_: tuple[str, ...], keep: int | None) → bool: Clean workdirs of runs

class tmt.base.core.Core(*, node: Tree, tree: Tree | None = None, parent: Common | None = None, logger: Logger, name: str | None = None, **kwargs: Any)

Bases: ValidateFmfMixin, LoadFmfKeysMixin, Common

General node object

Corresponds to given fmf.Tree node. Implements common Test, Plan and Story methods. Also defines L0 metadata and its manipulation.

Initialize the node

adjust: list[_RawAdjustRule] | None

property anchor_path: Path

author: list[str]

cli_invocation: 'tmt.cli.CliInvocation' | None = None

contact: list[str]

description: str | None = None

enabled: bool = True

property fmf_id: FmfId: Return full fmf identifier of the node

property fmf_root: Path | None

property fmf_sources: list[Path]

classmethod from_tree(tree: Tree) → list[Self]

Gather list of instances of this class in a given tree.

Helpful when looking for objects of a class derived from Core in a given tree, encapsulating the mapping between core classes and tree search methods.

Parameters:: tree – tree to search for objects.

property git_root: Path | None

has_link(needle: LinkNeedle) → bool: Whether object contains specified link

id: str | None = None

link: Links | None = None

lint_summary_exists() → Iterator[tuple[LinterOutcome, str]]: C001: summary key should be set and should be reasonably long

lint_validate() → Iterator[tuple[LinterOutcome, str]]: C000: fmf node should pass the schema validation

ls(summary: bool = False) → None: List node

name_and_summary() → str: Node name and optional summary

order: int = 50

classmethod store_cli_invocation(context: tmt.cli.Context | None, options: dict[str, Any] | None = None) → tmt.cli.CliInvocation: Save provided command line context for future use

summary: str | None = None

tag: list[str]

tier: str | None = None

web_link() → str | None: Return a clickable web link to the fmf metadata location

tmt.base.core.DEFAULT_ORDER = 50: The default order of any object.

class tmt.base.core.DependencyFile(type: str = 'file', pattern: list[str] = <factory>)

Bases: SpecBasedContainer[_RawDependencyFile, _RawDependencyFile], SerializableContainer, Exportable[DependencyFile]

VALID_KEYS: ClassVar[list[str]] = ['type', 'pattern']

classmethod from_spec(raw: _RawDependencyFile) → DependencyFile: Convert from a specification file or from a CLI option

pattern: list[str]

to_dict() → _RawDependencyFile: Return keys and values in the form of a dictionary

to_minimal_dict() → _RawDependencyFile: Convert to a mapping with unset keys omitted

type: str = 'file'

static validate() → tuple[bool, str]

Validate file dependency and return a human readable error

There is no way to check validity of type or pattern string at this time. Return a tuple (boolean, message) as the result of validation. The boolean specifies the validation result and the message the validation error. In case the file dependency is valid, return an empty string as the message.

Bases: FmfId, SpecBasedContainer[_RawDependencyFmfId, _RawDependencyFmfId]

A fmf ID as a dependency.

Not a pure fmf ID though, the form accepted by require & co. allows several extra keys.

VALID_KEYS: ClassVar[list[str]] = ['url', 'ref', 'path', 'name', 'destination', 'nick', 'type']

destination: Path | None = None

classmethod from_spec(raw: _RawDependencyFmfId) → DependencyFmfId: Convert from a specification file or from a CLI option

nick: str | None = None

to_dict() → _RawDependencyFmfId: Return keys and values in the form of a dictionary

to_minimal_dict() → _RawDependencyFmfId: Convert to a mapping with unset keys omitted

to_minimal_spec() → _RawDependencyFmfId: Convert to specification, skip default values

to_spec() → _RawDependencyFmfId: Convert to a form suitable for saving in a specification file

type: str = 'library'

class tmt.base.core.DependencySimple

Bases: str

A basic, simple dependency, usually a package

classmethod from_spec(spec: str) → DependencySimple

to_minimal_spec() → str

to_spec() → str

Bases: SpecBasedContainer[_RawFmfId, _RawFmfId], SerializableContainer, Exportable[FmfId]

NONEXPORTABLE_KEYS: ClassVar[list[str]] = ['fmf_root', 'git_root', 'default_branch']: Keys that are present, might be set, but shall not be exported.

VALID_KEYS: ClassVar[list[str]] = ['url', 'ref', 'path', 'name']

default_branch: str | None = None

fmf_root: Path | None = None

classmethod from_spec(raw: _RawFmfId) → FmfId: Convert from a specification file or from a CLI option

git_root: Path | None = None

name: str | None = None

path: Path | None = None

ref: str | None = None

resolve_dynamic_ref(git_repository: Path, plan: Plan) → None

Update ref with the final value for the dynamic reference.

ref remains unchanged when it is not a dynamic reference.

to_dict() → _RawFmfId: Return keys and values in the form of a dictionary

to_minimal_dict() → _RawFmfId: Convert to a mapping with unset keys omitted

to_minimal_spec() → _RawFmfId: Convert to specification, skip default values

to_spec() → _RawFmfId: Convert to a form suitable for saving in a specification file

url: str | None = None

validate() → tuple[bool, str]

Validate fmf id and return a human readable error

Return a tuple (boolean, message) as the result of validation. The boolean specifies the validation result and the message the validation error. In case the FMF id is valid, return an empty string as the message.

class tmt.base.core.Link(relation: Literal['verifies', 'verified-by', 'implements', 'implemented-by', 'documents', 'documented-by', 'blocks', 'blocked-by', 'duplicates', 'duplicated-by', 'parent', 'child', 'relates', 'test-script', 'note'], target: str | FmfId, note: str | None = None)

Bases: SpecBasedContainer[Any, dict[Literal[‘verifies’, ‘verified-by’, ‘implements’, ‘implemented-by’, ‘documents’, ‘documented-by’, ‘blocks’, ‘blocked-by’, ‘duplicates’, ‘duplicated-by’, ‘parent’, ‘child’, ‘relates’, ‘test-script’, ‘note’], str | _RawFmfId]]

An internal “link” as defined by tmt specification.

All links, after entering tmt internals, are converted from their raw representation into instances of this class.

[1] https://tmt.readthedocs.io/en/stable/spec/core.html#link

DEFAULT_RELATIONSHIP: ClassVar[Literal['verifies', 'verified-by', 'implements', 'implemented-by', 'documents', 'documented-by', 'blocks', 'blocked-by', 'duplicates', 'duplicated-by', 'parent', 'child', 'relates', 'test-script', 'note']] = 'relates'

classmethod from_spec(spec: str | _RawFmfId | dict[Literal['verifies', 'verified-by', 'implements', 'implemented-by', 'documents', 'documented-by', 'blocks', 'blocked-by', 'duplicates', 'duplicated-by', 'parent', 'child', 'relates', 'test-script', 'note'], str | _RawFmfId]) → Link

Convert from a specification file or from a CLI option

Specification is described in [1], this constructor takes care of parsing it into a corresponding Link instance.

[1] https://tmt.readthedocs.io/en/stable/spec/core.html#link

note: str | None = None

relation: Literal['verifies', 'verified-by', 'implements', 'implemented-by', 'documents', 'documented-by', 'blocks', 'blocked-by', 'duplicates', 'duplicated-by', 'parent', 'child', 'relates', 'test-script', 'note']

target: str | FmfId

to_spec() → dict[Literal['verifies', 'verified-by', 'implements', 'implemented-by', 'documents', 'documented-by', 'blocks', 'blocked-by', 'duplicates', 'duplicated-by', 'parent', 'child', 'relates', 'test-script', 'note'], str | _RawFmfId]

Convert to a form suitable for saving in a specification file

No matter what the original specification was, every link will generate the very same type of specification, the relation: target one.

Output of this method is fully compatible with specification, and when given to from_spec(), it shall create a Link instance with the same properties as the original one.

[1] https://tmt.readthedocs.io/en/stable/spec/core.html#link

class tmt.base.core.LinkNeedle(relation: str = '.*', target: str = '.*')

Bases: object

A container to use for searching links.

relation and target fields hold regular expressions that are to be searched for in the corresponding fields of Link instances.

classmethod from_spec(value: str) → LinkNeedle

Convert from a specification file or from a CLI option

Specification is described in [1], this constructor takes care of parsing it into a corresponding LinkNeedle instance.

[1] https://tmt.readthedocs.io/en/stable/plugins/discover.html#fmf

matches(link: Link) → bool: Find out whether a given link matches this needle

relation: str = '.*'

target: str = '.*'

class tmt.base.core.Links(*, data: str | _RawFmfId | dict[Literal['verifies', 'verified-by', 'implements', 'implemented-by', 'documents', 'documented-by', 'blocks', 'blocked-by', 'duplicates', 'duplicated-by', 'parent', 'child', 'relates', 'test-script', 'note'], str | _RawFmfId] | list[str | _RawFmfId | dict[Literal['verifies', 'verified-by', 'implements', 'implemented-by', 'documents', 'documented-by', 'blocks', 'blocked-by', 'duplicates', 'duplicated-by', 'parent', 'child', 'relates', 'test-script', 'note'], str | _RawFmfId]] | None = None)

Bases: SpecBasedContainer[Any, list[dict[Literal[‘verifies’, ‘verified-by’, ‘implements’, ‘implemented-by’, ‘documents’, ‘documented-by’, ‘blocks’, ‘blocked-by’, ‘duplicates’, ‘duplicated-by’, ‘parent’, ‘child’, ‘relates’, ‘test-script’, ‘note’], str | _RawFmfId]]]

Collection of links in tests, plans and stories.

Provides abstraction over the whole collection of object’s links.

[1] https://tmt.readthedocs.io/en/stable/spec/core.html#link

Create a collection from raw link data

classmethod from_spec(spec: str | _RawFmfId | dict[Literal['verifies', 'verified-by', 'implements', 'implemented-by', 'documents', 'documented-by', 'blocks', 'blocked-by', 'duplicates', 'duplicated-by', 'parent', 'child', 'relates', 'test-script', 'note'], str | _RawFmfId] | list[str | _RawFmfId | dict[Literal['verifies', 'verified-by', 'implements', 'implemented-by', 'documents', 'documented-by', 'blocks', 'blocked-by', 'duplicates', 'duplicated-by', 'parent', 'child', 'relates', 'test-script', 'note'], str | _RawFmfId]]) → Self

Convert from a specification file or from a CLI option

See https://tmt.readthedocs.io/en/stable/code/classes.html#class-conversions for more details.

See to_spec() for its counterpart.

get(relation: Literal['verifies', 'verified-by', 'implements', 'implemented-by', 'documents', 'documented-by', 'blocks', 'blocked-by', 'duplicates', 'duplicated-by', 'parent', 'child', 'relates', 'test-script', 'note'] | None = None) → list[Link]: Get links with given relation, all by default

has_link(needle: LinkNeedle | None = None) → bool

Check whether this set of links contains a matching link.

If needle is left unspecified, method would take all links into account, as if the needle was match all possible links (.*:.*). Method would then answer the question “are there any links at all?”

Parameters:: needle – if set, only links matching needle are considered. If not set, method considers all present links.
Returns:: True if there are matching links, False otherwise.

show() → None: Format a list of links with their relations

to_spec() → list[dict[Literal['verifies', 'verified-by', 'implements', 'implemented-by', 'documents', 'documented-by', 'blocks', 'blocked-by', 'duplicates', 'duplicated-by', 'parent', 'child', 'relates', 'test-script', 'note'], str | _RawFmfId]]

Convert to a form suitable for saving in a specification file

No matter what the original specification was, every link will generate the very same type of specification, the relation: target one.

Output of this method is fully compatible with specification, and when used to instantiate Link() object, it shall create a collection of links with the same properties as the original one.

[1] https://tmt.readthedocs.io/en/stable/spec/core.html#link

class tmt.base.core.LintableCollection(objs: list[Core], *args: Any, **kwargs: Any)

Bases: Lintable[LintableCollection]

Linting rules applied to a collection of Tests, Plans or Stories

lint_no_duplicate_ids() → Iterator[tuple[LinterOutcome, str]]: G001: no duplicate ids

print_header() → None

tmt.base.core.PLAN_SOURCE_SCRIPT_NAME: str = 'plan-source-script.sh': Filename associated with TMT_PLAN_SOURCE_SCRIPT

class tmt.base.core.Plan(*, node: Tree, tree: Tree | None = None, run: Run | None = None, skip_validation: bool = False, raise_on_validation_error: bool = False, inherited_fmf_context: FmfContext | None = None, inherited_environment: Environment | None = None, logger: Logger, **kwargs: Any)

Bases: HasRunWorkdir, HasPlanWorkdir, HasEnvironment, Core, Exportable[Plan], Lintable[Plan]

Plan object (L2 Metadata)

Initialize the plan

add_phase(step: str | Step, phase: Phase) → None

Add a phase dynamically to the current plan.

Parameters:

step – The (future) step in which to add the phase.
phase – The phase to add to the step.

ansible: PlanAnsible | None = None

cli_invocation: 'tmt.cli.CliInvocation' | None = None

context: FmfContext

static create(*, names: list[str], template: str, path: Path, force: bool = False, dry: bool | None = None, logger: Logger) → None: Create a new plan

derive_plan(derived_id: int, tests: dict[str, list[Test]]) → Plan

Create a new plan derived from this one.

New plan will inherit its attributes from this plan, its name would be combination of this plan’s name and derived_id. New plan will have its own workdir, a copy of this plan’s workdir.

Parameters:

derived_id – arbitrary number marking the new plan as Nth plan derived from this plan.
tests – lists of tests to limit the new plan to.

derived_id: int | None = None

draw_test_serial_number(test: Test) → int

static edit_template(raw_content: str) → str: Edit the default template with custom values

property environment: Environment

Environment variables of the plan.

Contains all environment variables collected from multiple sources (in the following order):

plan environment file,
plan’s environment and environment-file keys,
importing plan’s environment,
--environment and --environment-file options,
run’s environment,
plan’s properties.

property fmf_context: FmfContext

Fmf context of the plan.

Contains all context dimensions collected from multiple sources (in the following order):

plan’s context key,
importing plan’s context,
--context option.

gate: list[str]

go() → None: Execute the plan

header() → None

Show plan name and summary

Include one blank line to separate plans

property is_remote_plan_reference: bool: Check whether the plan is a remote plan reference

lint_discover_unknown_method() → Iterator[tuple[LinterOutcome, str]]: P004: discover step methods must be known

lint_empty_env_files() → Iterator[tuple[LinterOutcome, str]]: P008: environment files are not empty

lint_execute_not_defined() → Iterator[tuple[LinterOutcome, str]]: P002: execute step must be defined with “how”

lint_execute_unknown_method() → Iterator[tuple[LinterOutcome, str]]: P003: execute step methods must be known

lint_fmf_remote_ids_valid() → Iterator[tuple[LinterOutcome, str]]: P005: remote fmf ids must be valid

lint_phases_have_guests() → Iterator[tuple[LinterOutcome, str]]: P007: step phases require existing guests and roles

lint_step_data_is_valid() → Iterator[tuple[LinterOutcome, str]]: P009: step phases have valid data

lint_unique_names() → Iterator[tuple[LinterOutcome, str]]: P006: phases must have unique names

lint_unknown_keys() → Iterator[tuple[LinterOutcome, str]]: P001: all keys are known

login: Login | None = None

static overview(tree: Tree) → None: Show overview of available plans

property plan_environment_file: Path

property plan_source_script: Path

property plan_workdir: Path

Path to a plan workdir.

Raises:: GeneralError – when there is no plan workdir yet.

prune() → None: Remove all uninteresting files from the plan workdir

reshape(tests: list[TestOrigin]) → bool

Change the content of this plan by application of plan shaping plugins.

tmt.plugins.plan_shaper plugins are invoked and may mangle this plan and its content. This plan may be even removed from the queue, and replaced with many new plans.

Parameters:: tests – tests that should be considered by shaping plugins as part of this plan.
Returns:: True if the plan has been modified, False otherwise.

resolve_imports() → list[Plan]

Resolve possible references to remote plans.

Returns:: one or more plans replacing the current one. The current plan may also be one of the returned ones.

property run_workdir: Path

Path to a run workdir.

Raises:: GeneralError – when there is no current run, or the run does not have a workdir yet.

show() → None: Show plan details

step_names(enabled_only: bool = True, skip: list[str] | None = None) → Iterator[Literal['discover', 'provision', 'prepare', 'execute', 'report', 'finish', 'cleanup']]

Iterate over step names.

Parameters:

enabled_only – if set, only enabled steps would be listed.
skip – if step name is in this list, it would be skipped.

Yields:

step names.

steps(enabled_only: bool = True, skip: list[str] | None = None) → Iterator[Step]

Iterate over steps.

Parameters:

enabled_only – if set, only enabled steps would be listed.
skip – if step name is in this list, it would be skipped.

Yields:

instance of tmt.step.Step, representing each step.

wake() → None: Wake up all steps

class tmt.base.core.RemotePlanReference(fmf_root: tmt._compat.pathlib.Path | None = None, git_root: tmt._compat.pathlib.Path | None = None, default_branch: str | None = None, url: str | None = None, ref: str | None = None, path: tmt._compat.pathlib.Path | None = None, name: str | None = None, importing: tmt.base.core.RemotePlanReferenceImporting = <RemotePlanReferenceImporting.REPLACE: 'replace'>, scope: tmt.base.core.RemotePlanReferenceImportScope = <RemotePlanReferenceImportScope.FIRST_PLAN_ONLY: 'first-plan-only'>, inherit_context: bool = True, inherit_environment: bool = True, adjust_plans: list[tmt.base.core._RawAdjustRule] = <factory>)

Bases: FmfId, SpecBasedContainer[_RemotePlanReference, _RemotePlanReference]

VALID_KEYS: ClassVar[list[str]] = ['url', 'ref', 'path', 'name', 'importing', 'scope', 'inherit-context', 'inherit-environment', 'adjust-plans']

adjust_plans: list[_RawAdjustRule]

classmethod from_spec(raw: _RemotePlanReference) → RemotePlanReference: Convert from a specification file or from a CLI option

importing: RemotePlanReferenceImporting = 'replace'

inherit_context: bool = True

inherit_environment: bool = True

property name_pattern: Pattern[str]

scope: RemotePlanReferenceImportScope = 'first-plan-only'

to_dict() → _RemotePlanReference: Return keys and values in the form of a dictionary

to_minimal_dict() → _RemotePlanReference: Convert to a mapping with unset keys omitted

to_minimal_spec() → _RemotePlanReference: Convert to specification, skip default values

to_spec() → _RemotePlanReference: Convert to a form suitable for saving in a specification file

class tmt.base.core.RemotePlanReferenceImportScope(*values)

Bases: Enum

ALL_PLANS = 'all-plans'

FIRST_PLAN_ONLY = 'first-plan-only'

SINGLE_PLAN_ONLY = 'single-plan-only'

classmethod from_spec(spec: str) → RemotePlanReferenceImportScope

class tmt.base.core.RemotePlanReferenceImporting(*values)

Bases: Enum

BECOME_PARENT = 'become-parent'

REPLACE = 'replace'

classmethod from_spec(spec: str) → RemotePlanReferenceImporting

Bases: HasRunWorkdir, HasEnvironment, Common

Test run, a container of plans

Initialize tree, workdir and plans

cli_invocation: 'tmt.cli.CliInvocation' | None = None

copy_scripts() → None: Copy the tmt helper scripts under the running workdir into a new scripts directory.

data: RunData | None = None

property environment: Environment

Environment variables of the run.

Contains all environment variables collected from multiple sources (in the following order):

run’s environment, saved from the previous runs in the same workdir,
run’s environment, --environment and --environment-file options.

finish() → None: Check overall results, return appropriate exit code

follow() → None: Periodically check for new lines in the log.

go() → None: Go and do test steps for selected plans

load() → None: Load list of selected plans and enabled steps

load_from_workdir() → None

Load the run from its workdir, do not require the root in run.yaml to exist. Does 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 plan_queue: Sequence[Plan]

A list of plans remaining to be executed.

It is being populated via plans, but eventually, go() will remove plans from it as they get processed. plans will remain untouched and will represent all plans collected.

property plans: Sequence[Plan]: Test plans for execution

policies: list[Policy]: Run policies to apply to tests, plans and stories.

prepare_for_try(tree: Tree) → None: Prepare the run for the try command

property run_workdir: Path

Path to a run workdir.

Raises:: GeneralError – when there is no current run, or the run does not have a workdir yet.

property runner: GuestLocal

save() → None: Save list of selected plans and enabled steps

show_runner(logger: Logger) → None: Log facts about the machine on which tmt runs

swap_plans(plan: Plan, *others: Plan) → None

Replace given plan with one or more plans.

Parameters:

plan – a plan to remove.
others – plans to put into the queue instead of plans.

tree: Tree | None

class tmt.base.core.RunData(root: str | None, plans: list[str] | None, steps: list[str], remove: bool, environment: tmt.utils.Environment = <factory>)

Bases: SerializableContainer

environment: Environment: Stores the environment supplied via CLI over all uses of this workdir. CLI options provided to subsequent tmt run invocations are added into this set.

plans: list[str] | None

remove: bool

root: str | None

steps: list[str]

Bases: Common

Status of tmt work directories.

Initialize name and relation with the parent object

Prepare the workdir for provided id / directory path or generate a new workdir name if workdir=True given. Store command line context and options for future use if context is provided.

FIRST_COL_LEN = 11

LONGEST_STEP = 'provision'

cli_invocation: 'tmt.cli.CliInvocation' | None = None

static colorize_column(content: str) → str: Add color to a status column

static get_overall_plan_status(plan: Plan) → Literal['done', 'todo', 'discover', 'provision', 'prepare', 'execute', 'report', 'finish', 'cleanup']: Examines the plan status (find the last done step)

classmethod pad_with_spaces(string: str) → str: Append spaces to string to properly align the first column

plan_matches_filters(plan: Plan) → bool: Check if the given plan matches filters from the command line

print_header() → None: Print the header of the status table based on verbosity

print_plans_status(run: Run) → None: Display the status of each plan of the given run

print_run_status(run: Run) → None: Display the overall status of the run

print_verbose_status(run: Run) → None: Display the status of each step of the given run

process_run(run: Run) → None: Display the status of the given run based on verbosity

run_matches_filters(run: Run) → bool: Check if the given run matches filters from the command line

show() → None: Display the current status

class tmt.base.core.Story(*, node: Tree, tree: Tree | None = None, skip_validation: bool = False, raise_on_validation_error: bool = False, logger: Logger, **kwargs: Any)

Bases: Core, Exportable[Story], Lintable[Story]

User story object

Initialize the story

cli_invocation: 'tmt.cli.CliInvocation' | None = None

coverage(code: bool, test: bool, docs: bool) → tuple[bool, bool, bool]: Show story coverage

static create(*, names: list[str], template: str, path: Path, force: bool = False, dry: bool | None = None, logger: Logger) → None: Create a new story

property documented: list[Link]: Return links to relevant documentation

example: list[str]

classmethod from_tree(tree: Tree) → list[Story]

Gather list of instances of this class in a given tree.

Helpful when looking for objects of a class derived from Core in a given tree, encapsulating the mapping between core classes and tree search methods.

Parameters:: tree – tree to search for objects.

property implemented: list[Link]: Return links to relevant source code

lint_story() → Iterator[tuple[LinterOutcome, str]]: S002: story key must be defined

lint_unknown_keys() → Iterator[tuple[LinterOutcome, str]]: S001: all keys are known

static overview(tree: Tree) → None: Show overview of available stories

priority: StoryPriority | None = None

show() → None: Show story details

property status: list[str]: Aggregate story status from implemented-, verified- and documented-by links

story: str | None = None

title: str | None = None

property verified: list[Link]: Return links to relevant test coverage

class tmt.base.core.StoryPriority(*values)

Bases: Enum

COULD_HAVE = 'could have'

MUST_HAVE = 'must have'

SHOULD_HAVE = 'should have'

WILL_NOT_HAVE = 'will not have'

class tmt.base.core.Test(*, node: Tree, tree: Tree | None = None, skip_validation: bool = False, raise_on_validation_error: bool = False, logger: Logger, **kwargs: Any)

Bases: Core, Exportable[Test], Lintable[Test]

Test object (L1 Metadata)

Initialize test data from an fmf node or a dictionary

The following two methods are supported:

Test(node)

check: list[Check]

cli_invocation: 'tmt.cli.CliInvocation' | None = None

component: list[str]

static create(*, names: list[str], template: str, path: Path, script: str | None = None, force: bool = False, dry: bool | None = None, logger: Logger) → None: Create a new test

duration: str = '5m'

enabled_on_guest(guest: Guest) → bool: Check if the test is enabled on the specific guest

environment: Environment

framework: str = 'shell'

classmethod from_dict(*, mapping: dict[str, Any], name: str, skip_validation: bool = False, raise_on_validation_error: bool = False, logger: Logger, **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.

property ids: dict[str, str | None]: Get a dictionary with ids like tmt id, extra-nitrate and extra-task for report step

lint_absolute_path() → Iterator[tuple[LinterOutcome, str]]: T003: test directory path must be absolute

lint_defined_test() → Iterator[tuple[LinterOutcome, str]]: T002: test script must be defined

lint_legacy_coverage_key() → Iterator[tuple[LinterOutcome, str]]: T006: coverage has been obsoleted by link

lint_legacy_relevancy_rules() → Iterator[tuple[LinterOutcome, str]]: T005: relevancy has been obsoleted by adjust

lint_manual_test_path_exists() → Iterator[tuple[LinterOutcome, str]]: T007: manual test path is not an actual path

lint_manual_valid_markdown() → Iterator[tuple[LinterOutcome, str]]: T008: manual test should be valid markdown

lint_path_exists() → Iterator[tuple[LinterOutcome, str]]: T004: test directory path must exist

lint_require_type_field() → Iterator[tuple[LinterOutcome, str]]: T009: require fields should have type field

lint_unknown_keys() → Iterator[tuple[LinterOutcome, str]]: T001: all keys are known

manual: bool = False

property manual_test_path: Path

static overview(tree: Tree) → None: Show overview of available tests

path: Path | None = None

recommend: list[DependencySimple | DependencyFmfId | DependencyFile]

require: list[DependencySimple | DependencyFmfId | DependencyFile]

restart_max_count: int = 1

restart_on_exit_code: list[int]

restart_with_reboot: bool = False

result: ResultInterpret = 'respect'

serial_number: int = 0

show() → None: Show test details

show_manual() → None: Show manual test instructions

test: ShellScript | None = None

property test_framework: type[TestFramework]

tty: bool = False

where: list[str]

class tmt.base.core.Tree(*, path: Path | None = None, tree: Tree | None = None, fmf_context: FmfContext | None = None, additional_rules: list[_RawAdjustRule] | None = None, logger: Logger)

Bases: Common

Test Metadata Tree

Initialize tmt tree from directory path or given fmf tree

cli_invocation: 'tmt.cli.CliInvocation' | None = None

property fmf_context: FmfContext: Use custom fmf context if provided, default otherwise

classmethod grow(*, path: Path | None = None, tree: Tree | None = None, fmf_context: FmfContext | None = None, logger: Logger | None = None) → Tree

Initialize tmt tree from directory path or given fmf tree.

This method serves as an entry point for interactive use of tmt-as-a-library, providing sane defaults.

Warning

This method has a very limited use case, i.e. to help bootstrapping interactive tmt sessions. Using it anywhere outside of this scope should be ruled out.

static init(*, path: Path, template: str, force: bool, logger: Logger) → None: Initialize a new tmt tree, optionally with a template

plans(logger: Logger | None = None, keys: list[str] | None = None, names: list[str] | None = None, filters: list[str] | None = None, conditions: list[str] | None = None, run: Run | None = None, links: list[LinkNeedle] | None = None, excludes: list[str] | None = None, apply_command_line: bool = True) → list[Plan]: Search available plans

property root: Path | None: Metadata root

sanitize_cli_names(names: list[str]) → list[str]: Sanitize CLI names in case name includes control character

stories(logger: Logger | None = None, keys: list[str] | None = None, names: list[str] | None = None, filters: list[str] | None = None, conditions: list[str] | None = None, whole: bool = False, links: list[LinkNeedle] | None = None, excludes: list[str] | None = None, apply_command_line: bool | None = True) → list[Story]: Search available stories

tests(logger: Logger | None = None, keys: list[str] | None = None, names: list[str] | None = None, filters: list[str] | None = None, conditions: list[str] | None = None, unique: bool = True, links: list[LinkNeedle] | None = None, includes: list[str] | None = None, excludes: list[str] | None = None, apply_command_line: bool = True, sort: bool = True) → list[Test]: Search available tests

property tree: Tree: Initialize tree only when accessed

tmt.base.core.assert_simple_dependencies(dependencies: list[DependencySimple | DependencyFmfId | DependencyFile], error_message: str, logger: Logger) → list[DependencySimple]

Make sure the list of dependencies consists of simple ones.

Parameters:

dependencies – the list of requires.
error_message – used for a raised exception.
logger – used for logging.

Raises:

GeneralError – when there is a dependency on the list which is not a subclass of tmt.base.core.DependencySimple.

tmt.base.core.create_adjust_callback(logger: Logger) → AdjustCallback

Create a custom callback for fmf’s adjust.

Given the adjust rules are applied on many places, for proper logging they need their own specific logger. Create a callback closure with the given logger.

tmt.base.core.dependency_factory(raw_dependency: str | _RawDependencyFmfId | _RawDependencyFile | None) → DependencySimple | DependencyFmfId | DependencyFile: Select the correct require class

tmt.base.core.expand_node_data(data: T, fmf_context: FmfContext) → T: Recursively expand variables in node data

Normalize content of require key.

The requirements may be defined as either string or a special fmf id flavor, or a mixed list of these types. The goal here is to reduce the space of possibilities to a list, with fmf ids being converted to their internal representation.

tmt.base.core.resolve_dynamic_ref(*, workdir: Path, ref: str | None, plan: Plan | None = None, logger: Logger) → str | None

Get the final value for the dynamic reference

Returns original ref if the dynamic referencing isn’t used. Plan is used for context and environment expansion to process reference. Common instance is used for appropriate logging.

Module contents

Base Metadata Classes