Discover Plugins

Common Keys

The following keys are accepted by all plugins of the discover step.

name:

The name of the step phase.

order:

Order in which the phase should be handled.

Default: 50

summary:

Concise summary describing purpose of the phase.

Default: not set

where: GUEST|ROLE

Run this phase on given guest or guests with the given role only.

Default: not set

fmf

Warning

Please, be aware that the documentation below is a work in progress. We are working on fixing it, adding missing bits and generally making it better. Also, it was originally used for command line help only, therefore the formatting is often suboptimal.

Discover available tests from fmf metadata.

By default all available tests from the current repository are used so the minimal configuration looks like this:

discover:
    how: fmf

Full config example:

discover:
    how: fmf
    url: https://github.com/teemtee/tmt
    ref: main
    path: /fmf/root
    test: /tests/basic
    filter: 'tier: 1'

If no ref is provided, the default branch from the origin is used.

For DistGit repo one can extract sources first and discover tests from it by using distgit-source: true later in Prepare step. It can be used together with ref, path and url, however ref is not possible without using url.

discover:
    how: fmf
    dist-git-source: true

Related config options (all optional):

dist-git-merge - set to true if you want to copy in extracted sources to the local repo
dist-git-init - set to true and fmf init will be called inside extracted sources (at dist-git-extract or top directory)
dist-git-extract - directory (glob supported) to copy from extracted sources (defaults to inner fmf root)
dist-git-remove-fmf-root - set to true to remove fmf root from extracted sources

Selecting tests containing specified link is possible using link key accepting RELATION:TARGET format of values. Regular expressions are supported for both relation and target part of the value. Relation can be omitted to target match any relation.

discover:
    how: fmf
    link: verifies:.*issue/850$

It is also possible to limit tests only to those that have changed in git since a given revision. This can be particularly useful when testing changes to tests themselves (e.g. in a pull request CI).

Related config options (all optional):

modified-only - set to true if you want to filter modified tests
modified-url - fetched as “reference” remote in the test dir
modified-ref - the ref to compare against

Example to compare local repo against upstream main branch:

discover:
    how: fmf
    modified-only: True
    modified-url: https://github.com/teemtee/tmt
    modified-ref: reference/main

Note that internally the modified tests are appended to the list specified via test, so those tests will also be selected even if not modified.

Use the adjust-tests key to modify the discovered tests’ metadata directly from the plan. For example, extend the test duration for slow hardware or modify the list of required packages when you do not have write access to the remote test repository. The value should follow the adjust rules syntax.

The following example adds an avc check for each discovered test, doubles its duration and replaces each occurrence of the word python3.11 in the list of required packages.

discover:
    how: fmf
    adjust-tests:
      - check+:
          - how: avc
      - duration+: '*2'
        because: Slow system under test
        when: arch == i286
      - require~:
          - '/python3.11/python3.12/'

Configuration

See also Common Keys accepted by the plugin.

adjust-tests:

Modify metadata of discovered tests from the plan itself. Use the same format as for adjust rules.

Default: not set

dist-git-download-only: true|false

Just download the sources. No rpmbuild -bp, nor installation of require or buildddeps happens.

Default: false

dist-git-extract:

What to copy from extracted sources, globbing is supported. Defaults to the top fmf root if it is present, otherwise top directory (shortcut “/”).

Default: not set

dist-git-init: true|false

Initialize fmf root inside extracted sources (at dist-git-extract or top directory).

Default: false

dist-git-install-builddeps: true|false

Install package build dependencies according to the specfile.

Default: false

dist-git-merge: true|false

Merge copied sources and plan fmf root.

Default: false

dist-git-remove-fmf-root: true|false

Remove fmf root from extracted source (top one or selected by copy-path, happens before dist-git-extract.

Default: false

dist-git-require: PACKAGE

Additional required package to be present before sources are prepared.

Default: not set

dist-git-source: true|false

Download DistGit sources and rpmbuild -bp them (can be skipped).

Default: false

dist-git-type: fedora|centos|redhatgitlab

Use the provided DistGit handler instead of the auto detection.

Default: not set

exclude: REGEXP

Exclude tests matching given regular expression.

Default: not set

filter: FILTERS

Include only tests matching the filter.

Default: not set

fmf-id: true|false

Only print fmf identifiers of discovered tests to the standard output and exit.

Default: false

link: RELATION:TARGET

Filter by linked objects (regular expressions are supported for both relation and target).

Default: not set

modified-only: true|false

If set, select only tests modified since reference revision.

Default: false

modified-ref: REVISION

Branch, tag or commit specifying the reference git revision (if not provided, the default branch is used).

Default: not set

modified-url: REPOSITORY

URL of the reference git repository with fmf metadata.

Default: not set

path: ROOT

Path to the metadata tree root.

Default: not set

prune: true|false

Copy only immediate directories of executed tests and their required files.

Default: false

ref: REVISION

Branch, tag or commit specifying the git revision.

Default: not set

repository:

Default: not set

revision:

Default: not set

sync-repo: true|false

Force the sync of the whole git repo. By default, the repo is copied only if the used options require it.

Default: false

test: NAMES

Select tests by name.

Default: not set

upgrade-path:

Default: not set

url: REPOSITORY

URL of the git repository with fmf metadata.

Default: not set

shell

Warning

Please, be aware that the documentation below is a work in progress. We are working on fixing it, adding missing bits and generally making it better. Also, it was originally used for command line help only, therefore the formatting is often suboptimal.

Use provided list of shell script tests.

List of test cases to be executed can be defined manually directly in the plan as a list of dictionaries containing test name, actual test script and optionally a path to the test. Example config:

discover:
    how: shell
    tests:
      - name: /help/main
        test: tmt --help
      - name: /help/test
        test: tmt test --help
      - name: /help/smoke
        test: ./smoke.sh
        path: /tests/shell

For DistGit repo one can download sources and use code from them in the tests. Sources are extracted into $TMT_SOURCE_DIR, patches are applied by default. See options to install build dependencies or to just download sources without applying patches. To apply patches the prepare step has to be enabled.

discover:
    how: shell
    dist-git-source: true
    tests:
      - name: /upstream
        test: cd $TMT_SOURCE_DIR/*/tests && make test

To clone a remote repository and use it as a source specify url. It accepts also ref to checkout provided reference. Dynamic reference feature is supported as well.

discover:
    how: shell
    url: https://github.com/teemtee/tmt.git
    ref: "1.18.0"
    tests:
      - name: first test
        test: ./script-from-the-repo.sh

Configuration

See also Common Keys accepted by the plugin.

dist-git-download-only: true|false

Just download the sources. No rpmbuild -bp, nor installation of require or buildddeps happens.

Default: false

dist-git-install-builddeps: true|false

Install package build dependencies according to the specfile.

Default: false

dist-git-require: PACKAGE

Additional required package to be present before sources are prepared.

Default: not set

dist-git-source: true|false

Download DistGit sources and rpmbuild -bp them (can be skipped).

Default: false

dist-git-type: fedora|centos|redhatgitlab

Use the provided DistGit handler instead of the auto detection.

Default: not set

keep-git-metadata: true|false

Keep the git metadata if a repo is synced to guest.

Default: false

ref: REVISION

Branch, tag or commit specifying the git revision.

Default: not set

tests:

Default: not set

url: REPOSITORY

URL of the git repository with tests to be fetched.

Default: not set