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.

Note

The recipe stores a static snapshot of test metadata, but it does not include external files referenced by tests (for example, a script pointed to by test: script.sh). When a recipe is executed with tmt run --recipe ..., metadata such as require is taken from the recipe as saved. Later changes to the corresponding fmf files have no effect unless the recipe itself is updated. However, external files such as test scripts are fetched from the repository at execution time and may reflect changes made after the recipe was generated.

# 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
    environment: ...
    # 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:

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

Status: idea