.. _/spec/recipe:

Recipe
======
*As a user, I want tmt to generate a recipe file that can be reused to reproduce
a run with the exact same configuration, without requiring additional input.*

.. note:: This is a draft, the story is not implemented yet.

A recipe is a YAML file that captures a complete, static snapshot of a tmt
run after all dynamic evaluation has been resolved. It includes preprocessed
information about plans, tests, and run configuration, as well as links to the
``results.yaml`` files created in previous run. All environment variables included
in the recipe are evaluated.

Generated recipe can be edited, manually or by using a script, which allows users
to select only a subset of discovered tests to be reexecuted.

.. note::
    All git repositories specified in the recipe will be fetched again during the
    recipe execution.

.. note::
    When submitting a new run based on a recipe, the ``results-path`` key of the
    ``execute`` step is ignored. New results will be generated from the actual
    test execution. Users can use this key to access the results created
    in previous run to modify the recipe and filter the tests that should
    be reexecuted.

.. code-block:: yaml

    # Mapping, stores run configuration
    run:
        # String, path to the fmf root in the repository
        root: "/path/to/fmf/root"
        # Bool, whether to remove the run directory after the run is finished
        remove: false
        # Mapping, stores command line environment
        environment: ...
        # Mapping, stores command line context
        context: ...

    # Represents plans with all their steps
    plans:
        # String, name of the plan
      - name: /plan/name
        # Mapping, stores plan environment from various sources
        environment-from-fmf: ...
        environment-from-importing: ...
        environment-from-cli: ...
        environment-from-intrinsics: ...
        # Mapping, stores plan context
        context: ...

        # Represents all steps of this plan
        discover:
            # Bool, whether the step is enabled
            enabled: true
            # Represents all phases of this step
            phases:
              - name: default-0
                how: fmf
                order: 50
                ...
            # Represents all discovered tests
            tests:
              - name: /test/name
                summary: Test summary
                ...

        provision:
            enabled: true
            phases:
              - name: default-0
                how: local
                order: 50
                hardware:
                    memory: 8 GiB
                ...

        prepare:
            enabled: true
            phases:
              - name: default-0
                how: ansible
                order: 50
                # Local path to the playbook, or git reference
                playbook: ansible/packages.yml
                ...

        execute:
            enabled: true
            phases:
              - name: default-0
                how: tmt
                order: 50
                ...
            # String, relative path to the results file from the previous run
            results-path: plans/name/execute/results.yaml

        report:
            enabled: true
            phases:
              - name: default-0
                how: display
                order: 50
                ...

        finish:
            enabled: true
            phases:
              - name: default-0
                how: shell
                order: 50
                ...

        cleanup:
            enabled: true
            phases:
              - name: default-0
                how: tmt
                order: 50
                ...


**Examples:**


.. code-block:: yaml

   # Reproduce a run using a recipe file
   tmt run --recipe /path/to/recipe.yaml


**Status:** idea

* Relates to `https://github.com/teemtee/tmt/issues/2332 <https://github.com/teemtee/tmt/issues/2332>`_