In the case that some test are failing under abnormal circumstances, the
os-autoinst api offers the possibility to the tester to save a memory
dump and disk image when certain conditions are met.

> [!IMPORTANT]
> Currently only the QEMU backend is supported.

# How to use

Three methods are available to the test writer, `freeze_vm`,
`save_memory_dump` and `save_storage`.

The feature is enabled by calling the aforementioned methods, using a
[post_fail_hook](https://github.com/os-autoinst/openQA/blob/master/docs/WritingTests.asciidoc#how-to-write-tests)
and setting the test’s flags as fatal. The `save_memory_dump` and
`save_storage` methods can be however called at any point within the
test.

## save_memory_dump

The method `save_memory_dump` can be called at any point, but it is
recommended to use it within a post fail hook. Different filenames
should be provided if the dump is being used within the test itself (or
more than one memory dump is being created) if no filename is provided,
the test’s name will be used.

## freeze_vm

If it is supported by the backend `freeze_vm` will allow the vm to be
paused/frozen within the test. So that memory and disk dumps can be
extracted without any risk of data changing.

> [!NOTE]
> Call this method to ensure memory and disk dump refer to the same
> machine state.

## save_storage

If it is supported by the backend `save_storage` will save all storage
devices into backup. This can be called from anywhere within a test. For
multiple calls within a test module a filename needs to be specified. By
default it uses the test module name.

> [!NOTE]
> This method is time-consuming and requires a lot of space.

# Examples

A very simple way to use this helpful feature is the following:

``` perl
sub post_fail_hook ($self) {
    freeze_vm;
    save_memory_dump(filename => 'my-memory-dump');
}

sub test_flags ($) { { fatal => 1 } }
```

``` perl
    save_storage(filename => 'my-backup');
```
