= Memory Dumps

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 https://github.com/os-autoinst/openQA/blob/master/docs/WritingTests.asciidoc#how-to-write-tests[post_fail_hook] 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:

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

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

[source,perl]
----------------------------------------
    save_storage(filename => 'my-backup');
----------------------------------------
