diff --git a/spec/plans/discover.fmf b/spec/plans/discover.fmf index 9ad5296cc2..5440d438a9 100644 --- a/spec/plans/discover.fmf +++ b/spec/plans/discover.fmf @@ -57,20 +57,6 @@ description: | within the same discover config, use :ref:`multiple-configs` instead. - url - Git repository, used directly as a git clone argument. - - ref - Branch, tag or commit specifying the desired git - revision. Defaults to the remote repository's default - branch. - - keep-git-metadata - By default the ``.git`` directory is removed to save - disk space. Set to ``true`` to sync the git metadata - to guest as well. Implicit if ``dist-git-source`` is - used. - Use the :ref:`/spec/plans/discover/dist-git-source` options to download rpm sources for dist-git repositories. @@ -105,108 +91,9 @@ description: | summary: Discover available tests using the fmf format description: | Use the `Flexible Metadata Format`_ to explore all - available tests in given repository. The following - parameters are supported: - - url - Git repository containing the metadata tree. - Current git repository used by default. - ref - Branch, tag or commit specifying the desired git - revision. Defaults to the remote repository's default - branch if url given or to the current ``HEAD`` if url - not provided. - - Additionally, one can set ``ref`` dynamically. This is - possible using a special file in tmt format stored in - the *default* branch of a tests repository. This special - file should contain rules assigning attribute ``ref`` - in an `adjust` block, for example depending on a test - run context. - - Dynamic ``ref`` assignment is enabled whenever a test - plan reference has the format ``ref: @FILEPATH``. - path - Path to the metadata tree root. Must be relative to - the git repository root if url provided, absolute - local filesystem path otherwise. By default ``.`` is - used. - - See also the `fmf identifier`_ documentation for details. - Use the following keys to limit the test discovery by test - name, an advanced filter or link: - - test - List of test names or regular expressions used to - select tests by name. Duplicate test names are allowed - to enable repetitive test execution, preserving the - listed test order. - link - Select tests using the :ref:`/spec/core/link` keys. - Values must be in the form of ``RELATION:TARGET``, - tests containing at least one of them are selected. - Regular expressions are supported for both relation - and target. Relation part can be omitted to match all - relations. - filter - Apply advanced filter based on test metadata - attributes. See ``pydoc fmf.filter`` for more info. - exclude - Exclude tests which match a regular expression. - prune - Copy only immediate directories of executed tests and - their required files. - - .. versionadded:: 1.29 - - 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) are: - - modified-only - Set to ``true`` if you want to filter modified tests - only. The test is modified if its name starts with - the name of any directory modified since modified-ref. - modified-url - An additional remote repository to be used as the - reference for comparison. Will be fetched as a - ``reference`` remote in the test dir. - modified-ref - The ref to compare against. Defaults to the local - repository's default branch. Note that you need to - specify ``reference/`` to compare to a branch - from the repository specified in ``modified-url``. + available tests in given repository. - Use the :ref:`/spec/plans/discover/dist-git-source` - options to download rpm sources for dist-git repositories. - In addition to the common dist-git-source features, the - ``fmf`` plugin also supports the following options: - - dist-git-init - Set to ``true`` to initialize fmf root inside - extracted sources at ``dist-git-extract`` location or - top directory. To be used when the sources contain fmf - files (for example tests) but do not have an - associated fmf root. - - dist-git-remove-fmf-root - Set to ``true`` to remove any fmf root present in the - sources. ``dist-git-init`` can be used to create it - later at desired location. - - dist-git-merge - Set to ``true`` to combine fmf root from the sources - and fmf root from the plan. It allows to have plans - and tests defined in the DistGit repo which use tests - and other resources from the downloaded sources. Any - plans in extracted sources will not be processed. - - dist-git-extract - Path specifying what should be copied from the - sources. Defaults to top fmf root or top directory - ``/``. + See the `fmf identifier`_ documentation for details. .. _fmf identifier: https://fmf.readthedocs.io/en/latest/concept.html#identifiers .. _Flexible Metadata Format: https://fmf.readthedocs.io/ @@ -262,34 +149,6 @@ description: | order ``60``. All created files and directories by this command are directly in ``TMT_SOURCE_DIR``. - .. versionadded:: 1.32 - - dist-git-source - Download and (optionally) extract the sources. - - dist-git-type - Use the provided DistGit handler instead of the auto - detection. Useful when running from forked - repositories. - - dist-git-download-only - When ``true`` sources are just downloaded. - No ``rpmbuild -bp``, nor installation of require - or buildddeps happens. - - .. versionadded:: 1.29 - - dist-git-require - List of packages to install before ``rpmbuild -bp`` is attempted - on the sources. The rpm-build package itself is installed automatically. - - .. versionadded:: 1.32 - - dist-git-install-builddeps - When set to ``true`` build requirements are installed. - - .. versionadded:: 1.32 - The :ref:`/spec/plans/discover/fmf` plugin supports additional dist-git options, see its documentation for details. diff --git a/tmt/steps/discover/__init__.py b/tmt/steps/discover/__init__.py index 310914d90d..b69ee2d489 100644 --- a/tmt/steps/discover/__init__.py +++ b/tmt/steps/discover/__init__.py @@ -48,7 +48,10 @@ class DiscoverStepData(tmt.steps.WhereableStepData, tmt.steps.StepData): default=None, option='--dist-git-type', choices=tmt.utils.get_distgit_handler_names, - help='Use the provided DistGit handler instead of the auto detection.', + help=""" + Use the provided DistGit handler instead of the auto detection. + Useful when running from forked repositories. + """, ) dist_git_download_only: bool = field( @@ -71,7 +74,10 @@ class DiscoverStepData(tmt.steps.WhereableStepData, tmt.steps.StepData): option="--dist-git-require", metavar='PACKAGE', multiple=True, - help='Additional required package to be present before sources are prepared.', + help=""" + Additional required package to be present before sources are prepared. + The rpm-build package itself is installed automatically. + """, # *simple* requirements only normalize=lambda key_address, value, logger: tmt.base.assert_simple_dependencies( tmt.base.normalize_require(key_address, value, logger), diff --git a/tmt/steps/discover/fmf.py b/tmt/steps/discover/fmf.py index a29a8ed98e..300cc76772 100644 --- a/tmt/steps/discover/fmf.py +++ b/tmt/steps/discover/fmf.py @@ -44,20 +44,43 @@ class DiscoverFmfStepData(tmt.steps.discover.DiscoverStepData): default=cast(Optional[str], None), option=('-u', '--url'), metavar='REPOSITORY', - help='URL of the git repository with fmf metadata.', + help=""" + Git repository containing the metadata tree. + Current git repository used by default. + """, ) + ref: Optional[str] = field( default=cast(Optional[str], None), option=('-r', '--ref'), metavar='REVISION', - help='Branch, tag or commit specifying the git revision.', + help=""" + Branch, tag or commit specifying the desired git + revision. Defaults to the remote repository's default + branch if ``url`` was set or to the current ``HEAD`` + of the current repository. + + Additionally, one can set ``ref`` dynamically. + This is possible using a special file in tmt format + stored in the *default* branch of a tests repository. + This special file should contain rules assigning attribute ``ref`` + in an *adjust* block, for example depending on a test run context. + + Dynamic ``ref`` assignment is enabled whenever a test plan + reference has the format ``ref: @FILEPATH``. + """, normalize=normalize_ref, ) + path: Optional[str] = field( default=cast(Optional[str], None), option=('-p', '--path'), metavar='ROOT', - help='Path to the metadata tree root.', + help=""" + Path to the metadata tree root. Must be relative to + the git repository root if ``url`` was provided, absolute + local filesystem path otherwise. By default ``.`` is used. + """, ) # Selecting tests @@ -66,25 +89,39 @@ class DiscoverFmfStepData(tmt.steps.discover.DiscoverStepData): option=('-t', '--test'), metavar='NAMES', multiple=True, - help='Select tests by name.', + help=""" + List of test names or regular expressions used to + select tests by name. Duplicate test names are allowed + to enable repetitive test execution, preserving the + listed test order. + """, normalize=tmt.utils.normalize_string_list, ) + link: list[str] = field( default_factory=list, option='--link', metavar="RELATION:TARGET", multiple=True, help=""" - Filter by linked objects (regular expressions are supported for both relation and - target). + Select tests using the :ref:`/spec/core/link` keys. + Values must be in the form of ``RELATION:TARGET``, + tests containing at least one of them are selected. + Regular expressions are supported for both relation + and target. Relation part can be omitted to match all + relations. """, ) + filter: list[str] = field( default_factory=list, option=('-F', '--filter'), metavar='FILTERS', multiple=True, - help='Include only tests matching the filter.', + help=""" + Apply advanced filter based on test metadata attributes. + See ``pydoc fmf.filter`` for more info. + """, normalize=tmt.utils.normalize_string_list, ) exclude: list[str] = field( @@ -101,21 +138,32 @@ class DiscoverFmfStepData(tmt.steps.discover.DiscoverStepData): default=False, option=('-m', '--modified-only'), is_flag=True, - help='If set, select only tests modified since reference revision.', + help=""" + Set to ``true`` if you want to filter modified tests + only. The test is modified if its name starts with + the name of any directory modified since ``modified-ref``. + """, ) + modified_url: Optional[str] = field( default=cast(Optional[str], None), option='--modified-url', metavar='REPOSITORY', - help='URL of the reference git repository with fmf metadata.', + help=""" + An additional remote repository to be used as the + reference for comparison. Will be fetched as a + reference remote in the test dir. + """, ) + modified_ref: Optional[str] = field( default=cast(Optional[str], None), option='--modified-ref', metavar='REVISION', help=""" - Branch, tag or commit specifying the reference git revision (if not provided, the - default branch is used). + The branch, tag or commit specifying the reference git revision (if not provided, the + default branch is used). Note that you need to specify ``reference/`` to + compare to a branch from the repository specified in ``modified-url``. """, ) @@ -125,7 +173,10 @@ class DiscoverFmfStepData(tmt.steps.discover.DiscoverStepData): option='--dist-git-init', is_flag=True, help=""" - Initialize fmf root inside extracted sources (at dist-git-extract or top directory). + Set to ``true`` to initialize fmf root inside extracted sources at + ``dist-git-extract`` location or top directory. To be used when the + sources contain fmf files (for example tests) but do not have an + associated fmf root. """, ) dist_git_remove_fmf_root: bool = field( @@ -141,7 +192,12 @@ class DiscoverFmfStepData(tmt.steps.discover.DiscoverStepData): default=False, option='--dist-git-merge', is_flag=True, - help='Merge copied sources and plan fmf root.', + help=""" + Set to ``true`` to combine fmf root from the sources and fmf root from the plan. + It allows to have plans and tests defined in the DistGit repo which use tests + and other resources from the downloaded sources. Any plans in extracted sources + will not be processed. + """, ) dist_git_extract: Optional[str] = field( default=cast(Optional[str], None), @@ -250,17 +306,6 @@ class DiscoverFmf(tmt.steps.discover.DiscoverPlugin[DiscoverFmfStepData]): 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 @@ -276,12 +321,6 @@ class DiscoverFmf(tmt.steps.discover.DiscoverPlugin[DiscoverFmfStepData]): 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: .. code-block:: yaml diff --git a/tmt/steps/discover/shell.py b/tmt/steps/discover/shell.py index 6508e81698..fe85d7f9bf 100644 --- a/tmt/steps/discover/shell.py +++ b/tmt/steps/discover/shell.py @@ -194,14 +194,21 @@ class DiscoverShellData(tmt.steps.discover.DiscoverStepData): option="--ref", metavar='REVISION', default=None, - help="Branch, tag or commit specifying the git revision.", + help=""" + Branch, tag or commit specifying the desired git revision. + Defaults to the remote repository's default branch. + """, ) keep_git_metadata: bool = field( option="--keep-git-metadata", is_flag=True, default=False, - help="Keep the git metadata if a repo is synced to guest.", + help=""" + By default the ``.git`` directory is removed to save disk space. + Set to ``true`` to sync the git metadata to guest as well. + Implicit if ``dist-git-source`` is used. + """, ) def to_spec(self) -> tmt.steps._RawStepData: @@ -225,8 +232,10 @@ class DiscoverShell(tmt.steps.discover.DiscoverPlugin[DiscoverShellData]): 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: + in the plan as a list of dictionaries containing test ``name``, actual + ``test`` script and optionally the ``duration`` or a ``path`` to the test. + The default duration for tests defined directly in the discover step is ``1h``. + Example config: .. code-block:: yaml diff --git a/tmt/utils/rest.py b/tmt/utils/rest.py index c7f4a613bd..2ee4431c2b 100644 --- a/tmt/utils/rest.py +++ b/tmt/utils/rest.py @@ -201,6 +201,13 @@ def visit_literal(self, node: docutils.nodes.literal) -> None: depart_literal = _noop_departure + def visit_emphasis(self, node: docutils.nodes.literal) -> None: + self.log_visit(str(node)) + + self._emit(click.style(node.astext(), fg='yellow')) + + depart_emphasis = _noop_departure + def visit_literal_block(self, node: docutils.nodes.literal_block) -> None: self.log_visit(str(node))