tmt.checks package

Submodules

tmt.checks.avc module

tmt.checks.avc.AUSEARCH_MARK_FILENAME = 'avc-mark.txt': The filename of the “mark” file ausearch on the guest.

class tmt.checks.avc.AvcCheck(how: str, enabled: bool = True, result: tmt.checks.CheckResultInterpret = <CheckResultInterpret.RESPECT: 'respect'>, test_method: tmt.checks.avc.TestMethod = <TestMethod.TIMESTAMP: 'timestamp'>, delay_before_report: int = 5, ignore_pattern: list[re.Pattern[str]] = <factory>)

Bases: Check

delay_before_report: int = 5

ignore_pattern: list[Pattern[str]]

test_method: TestMethod = 'timestamp'

to_spec() → _RawCheck

Convert to a form suitable for saving in a specification file

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

See from_spec() for its counterpart.

class tmt.checks.avc.AvcDenials(*args: Any, **kwargs: Any)

Bases: CheckPlugin[AvcCheck]

Check for SELinux AVC denials raised during the test.

The check collects SELinux AVC denials from the audit log, gathers details about them, and together with versions of the selinux-policy and related packages stores them in a report file after the test.

check:
  - name: avc

Note

To work correctly, the check requires SELinux to be enabled on the guest, and auditd must be running. Without SELinux, the check will turn into no-op, reporting skip result, and without auditd, the check will discover no AVC denials, reporting pass.

If the test manipulates auditd or SELinux in general, the check may report unexpected results.

Added in version 1.28.

classmethod after_test(*, check: AvcCheck, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]

classmethod before_test(*, check: AvcCheck, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]

classmethod essential_requires(guest: Guest, test: tmt.base.Test, logger: Logger) → list[tmt.base.DependencySimple]

Collect all essential requirements of the test check.

Essential requirements of a check are necessary for the check to perform its basic functionality.

Returns:: a list of requirements.

tmt.checks.avc.DEFAULT_MESSAGE_TYPES = ['AVC', 'USER_AVC', 'SELINUX_ERR']: Default message types to be collected by ausearch

tmt.checks.avc.DENIAL_PATTERN = re.compile('^type=(?:AVC|USER_AVC|SELINUX_ERR)\\b'): Compiled regex pattern to match relevant AVC denial messages

tmt.checks.avc.INTERESTING_PACKAGES = ['audit', 'selinux-policy']: Packages related to selinux and AVC reporting. Their versions would be made part of the report.

tmt.checks.avc.TEST_POST_AVC_FILENAME = 'avc.txt': The filename of the final check report file.

class tmt.checks.avc.TestMethod(*values)

Bases: Enum

CHECKPOINT = 'checkpoint'

TIMESTAMP = 'timestamp'

classmethod from_spec(spec: str) → TestMethod

classmethod normalize(key_address: str, value: Any, logger: Logger) → TestMethod

tmt.checks.avc.create_ausearch_mark(invocation: TestInvocation, check: AvcCheck, logger: Logger) → None: Save a mark for ausearch in a file on the guest

tmt.checks.avc.create_final_report(invocation: TestInvocation, check: AvcCheck, logger: Logger) → tuple[ResultOutcome, list[Path]]: Collect the data, evaluate and create the final report

tmt.checks.coredump module

class tmt.checks.coredump.Coredump(*args: Any, **kwargs: Any)

Bases: CheckPlugin[CoredumpCheck]

Check for system crashes using coredump.

The check monitors for any crashes caught by systemd-coredump during test execution. This includes segmentation faults and other crashes that produce core dumps. By default, any crash will cause the test to fail.

Example config with optional ignore patterns:

check:
  - how: coredump
    ignore-pattern:
      - 'Process.*\(sleep\).*dumped core'  # Ignore sleep crashes
      - 'Package: ddcutil/2.1.2-2.fc41'      # Ignore dumps of a specific package

The patterns are matched against the full coredumpctl info output, which includes fields like Process, Command Line, Signal, etc. You can use ‘coredumpctl info’ to see the available fields and their format.

Common pattern examples:

Ignore all crashes from a specific process: ‘Process.*(specific-process)’
Ignore crashes with a specific signal: ‘Signal: .*(SIGSEGV)’
Ignore crashes from a specific package: ‘Package: package-name/.*’
Ignore crashes during a specific command: ‘Command Line: .*specific-command-pattern.*’

Added in version 1.46.

classmethod after_test(*, check: CoredumpCheck, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]: Check for crashes after the test finishes.

classmethod before_test(*, check: CoredumpCheck, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]: Check for crashes before the test starts.

class tmt.checks.coredump.CoredumpCheck(how: str, enabled: bool = True, result: ~tmt.checks.CheckResultInterpret = CheckResultInterpret.RESPECT, ignore_pattern: list[~re.Pattern[str]] = <factory>, is_available: bool = True, is_availability_reason: str | None = None, coredump_last_dumps_filepath: ~tmt._compat.pathlib.Path = <factory>)

Bases: Check

Configuration for the coredump check.

coredump_last_dumps_filepath: Path

ignore_pattern: list[Pattern[str]]

is_availability_reason: str | None = None

is_available: bool = True

to_minimal_spec() → _RawCheck: Convert to minimal raw specification.

to_spec() → _RawCheck: Convert to raw specification.

tmt.checks.dmesg module

class tmt.checks.dmesg.Dmesg(*args: Any, **kwargs: Any)

Bases: CheckPlugin[DmesgCheck]

Save the content of kernel ring buffer (aka “console”) into a file.

The check saves one file before the test, and then again when test finishes.

check:
  - how: dmesg

Check will identify patterns that signal kernel crashes and core dumps, and when detected, it will report as failed result. It is possible to define custom patterns:

check:
  - how: dmesg
    failure-pattern:
      # These are default patterns
      - 'Call Trace:
      - '\ssegfault\s'

      # More patterns to look for
      - '\[Firmware Bug\]'

Added in version 1.28.

Changed in version 1.33: failure-pattern has been added.

classmethod after_test(*, check: DmesgCheck, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]

classmethod before_test(*, check: DmesgCheck, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]

classmethod essential_requires(guest: Guest, test: tmt.base.Test, logger: Logger) → list[tmt.base.DependencySimple]

Collect all essential requirements of the test check.

Essential requirements of a check are necessary for the check to perform its basic functionality.

Returns:: a list of requirements.

class tmt.checks.dmesg.DmesgCheck(how: str, enabled: bool = True, result: tmt.checks.CheckResultInterpret = <CheckResultInterpret.RESPECT: 'respect'>, failure_pattern: list[re.Pattern[str]] = <factory>)

Bases: Check

failure_pattern: list[Pattern[str]]

to_minimal_spec() → _RawCheck

Convert to specification, skip default values

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

See from_spec() for its counterpart.

to_spec() → _RawCheck

Convert to a form suitable for saving in a specification file

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

See from_spec() for its counterpart.

tmt.checks.journal module

tmt.checks.journal.JOURNALCTL_CURSOR_FILENAME = 'journal-cursor.txt': The filename of the “mark” file journalctl on the guest.

class tmt.checks.journal.Journal(*args: Any, **kwargs: Any)

Bases: CheckPlugin[JournalCheck]

Check messages in journal log recorded during the test.

This check uses journalctl to capture log messages created during the test execution. It uses cursors to precisely pinpoint the start and end of the logging period.

The check automatically configures systemd journal with persistent storage and compression to ensure reliable log capture during test execution. Configuration is applied with appropriate permission handling and fallback behavior.

Example usage:

check:
  - how: journal
    # Check only kernel messages
    dmesg: true

check:
  - how: journal
    # Check messages from a specific systemd unit
    unit: httpd.service
    # Filter by priority
    priority: err

check:
  - how: journal
    # Check messages from a specific syslog identifier
    identifier: sshd
    priority: warning

Check will identify patterns that signal kernel crashes and core dumps, and when detected, it will report a failed result. It is possible to define custom patterns for failures and messages to ignore:

check:
  - how: journal
    failure-pattern:
      # These are default patterns
      - 'Call Trace:'
      - '\ssegfault\s'

      # More patterns to look for
      - '\[Firmware Bug\]'
    ignore-pattern:
      - 'a known harmless error message'

The check requires systemd to be available on the guest system. Journal configuration is automatically applied at the start of test execution, with fallback to default settings if configuration fails due to insufficient permissions.

Added in version 1.54.0.

classmethod after_test(*, check: JournalCheck, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]

classmethod before_test(*, check: JournalCheck, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]

class tmt.checks.journal.JournalCheck(how: str, enabled: bool = True, result: tmt.checks.CheckResultInterpret = <CheckResultInterpret.RESPECT: 'respect'>, failure_pattern: list[re.Pattern[str]] = <factory>, ignore_pattern: list[re.Pattern[str]] = <factory>, dmesg: bool = False, unit: str | None = None, identifier: str | None = None, priority: str | None = None)

Bases: Check

dmesg: bool = False

failure_pattern: list[Pattern[str]]

identifier: str | None = None

ignore_pattern: list[Pattern[str]]

priority: str | None = None

to_minimal_spec() → _RawCheck

Convert to specification, skip default values

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

See from_spec() for its counterpart.

to_spec() → _RawCheck

Convert to a form suitable for saving in a specification file

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

See from_spec() for its counterpart.

unit: str | None = None

tmt.checks.journal.TEST_POST_JOURNAL_FILENAME = 'journal.txt': The filename of the final check report file.

tmt.checks.watchdog module

class tmt.checks.watchdog.GuestContext(ping_failures: int = 0, ssh_ping_failures: int = 0, thread: Thread | None = None, keep_running: bool = True)

Bases: object

Per-guest watchdog context

keep_running: bool = True: As long as this field is set to True, the watchdog will run its internal loop and run relevant checks. It is unset when terminating the watchdog check to notify the thread it’s time to quit.

ping_failures: int = 0: Current number of failed watchdog checks.

ssh_ping_failures: int = 0

thread: Thread | None = None: If set, contains a daemonized thread running the watchdog checks.

class tmt.checks.watchdog.Watchdog(*args: Any, **kwargs: Any)

Bases: CheckPlugin[WatchdogCheck]

Take various actions when guest becomes unresponsive.

Watchdog runs selected probes every now and then, and when a given number of probes fail, watchdog would run one or more of the predefined actions.

Check comes with two probes, “ping” and “SSH ping”, and single action, “reboot”.

“ping” uses the classic ICMP echo to check whether the guest is still up and running,
“SSH ping” tries to establish SSH connection,
“reboot” action issues a hard reboot of the guest.

Warning

Be aware that this feature may be limited depending on how the guest was provisioned. See Hard reboot.

Each probe has a “budget” of allowed failures, and when it runs out, the action is taken. A successful probe replenishes its budget to the original level.

Multiple probes can be enabled at the same time, for the action to happen it’s enough if just one of them runs out of its budget.

check:
  - how: watchdog
    ping: true
    reboot: true

check:
  - how: watchdog

    # Use only SSH ping.
    ping: false
    ssh-ping: true

    # Try every 5 minutes, allow 7 failed attempts, and reboot
    # the guest when we run out of attempts.
    interval: 300
    reboot: true
    ssh-ping-threshold: 7

Added in version 1.32.

classmethod after_test(*, check: WatchdogCheck, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]

classmethod before_test(*, check: WatchdogCheck, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]

class tmt.checks.watchdog.WatchdogCheck(how: str, enabled: bool = True, result: tmt.checks.CheckResultInterpret = <CheckResultInterpret.RESPECT: 'respect'>, interval: int = 60, reboot: bool = False, ping: bool = False, ping_packets: int = 1, ping_threshold: int = 10, ssh_ping: bool = False, ssh_ping_threshold: int = 10)

Bases: Check

do_ping(invocation: TestInvocation, guest_context: GuestContext, logger: Logger) → None: Perform a ping check

do_ssh_ping(invocation: TestInvocation, guest_context: GuestContext, logger: Logger) → None: Perform a “SSH ping” check

interval: int = 60

notify(invocation: TestInvocation, logger: Logger) → None: Notify invocation that hard reboot is required

ping: bool = False

ping_packets: int = 1

ping_threshold: int = 10

reboot: bool = False

ssh_ping: bool = False

ssh_ping_threshold: int = 10

tmt.checks.watchdog.render_report_path(invocation: TestInvocation) → Path: Render path to a watchdog report file from necessary components

tmt.checks.watchdog.report_progress(log: Path, check_name: str, report: Iterable[str], command_output: str | None = None) → None

Add new report into a report file.

Parameters:

log – path to the report file.
report – iterable of report lines to add. Each line is emitted on its own line in the file.
command_output – if set, the string is added to the report file once report lines are written into it.

Module contents

class tmt.checks.Check(how: str, enabled: bool = True, result: CheckResultInterpret = CheckResultInterpret.RESPECT)

Bases: SpecBasedContainer[_RawCheck, _RawCheck], SerializableContainer, NormalizeKeysMixin

Represents a single check from test’s check field.

Serves as a link between raw fmf/CLI specification and an actual check implementation/plugin.

classmethod create_internal(logger: Logger) → Check | None

Create an internal check instance.

Parameters:: logger – logger to use for logging.
Returns:: a new instance of the check.

enabled: bool = True

classmethod from_spec(raw_data: _RawCheck, logger: Logger) → Check

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.

go(*, event: CheckEvent, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]

Run the check.

Parameters:

event – when the check is running - before the test, after the test, etc.
invocation – test invocation to which the check belongs to.
environment – optional environment to set for the check.
logger – logger to use for logging.

Returns:

list of results produced by checks.

how: str

property plugin: type[CheckPlugin[Any]]

result: CheckResultInterpret = 'respect'

to_minimal_spec() → _RawCheck

Convert to specification, skip default values

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

See from_spec() for its counterpart.

to_spec() → _RawCheck

Convert to a form suitable for saving in a specification file

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

See from_spec() for its counterpart.

class tmt.checks.CheckEvent(*values)

Bases: Enum

Events in test runtime when a check can be executed

AFTER_TEST = 'after-test'

BEFORE_TEST = 'before-test'

classmethod from_spec(spec: str) → CheckEvent

class tmt.checks.CheckPlugin(*args: Any, **kwargs: Any)

Bases: _CommonBase, Generic[CheckT]

Base class for plugins providing extra checks before, during and after tests

classmethod after_test(*, check: CheckT, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]

classmethod before_test(*, check: CheckT, invocation: TestInvocation, environment: Environment | None = None, logger: Logger) → list[CheckResult]

classmethod delegate(*, raw_data: _RawCheck, logger: Logger) → Check: Create a check data instance for the plugin

classmethod essential_requires(guest: Guest, test: tmt.base.Test, logger: Logger) → list[tmt.base.DependencySimple]

Collect all essential requirements of the test check.

Essential requirements of a check are necessary for the check to perform its basic functionality.

Returns:: a list of requirements.

classmethod internal_checks(logger: Logger) → list[Check]: Create internal check data instances

class tmt.checks.CheckResultInterpret(*values)

Bases: Enum

INFO = 'info'

RESPECT = 'respect'

XFAIL = 'xfail'

classmethod from_spec(spec: str) → CheckResultInterpret

to_spec() → str

class tmt.checks.CheckT

A type variable representing a Check instances.

alias of TypeVar(‘CheckT’, bound=Check)

tmt.checks.find_plugin(name: str) → type[CheckPlugin[Any]]

Find a plugin by its name.

Raises:: GeneralError – when the plugin does not exist.

tmt.checks.normalize_test_check(key_address: str, raw_test_check: Any, logger: Logger) → Check: Normalize a single test check

tmt.checks.normalize_test_checks(key_address: str, raw_checks: Any, logger: Logger) → list[Check]: Normalize (prepare/finish/test) checks

tmt.checks package

Subpackages

Submodules

tmt.checks.avc module

tmt.checks.coredump module

tmt.checks.dmesg module

tmt.checks.journal module

tmt.checks.watchdog module

Module contents