mention main.pm architecture in README

Differential Revision: https://phab.qadevel.cloud.fedoraproject.org/D495
This commit is contained in:
Jan Sedlák 2015-08-11 13:30:42 +02:00
parent 8fde224dc5
commit 5438b452d2
2 changed files with 66 additions and 17 deletions

View File

@ -7,35 +7,83 @@ Docker images, see [this repository](https://bitbucket.org/rajcze/openqa_fedora_
Test development Test development
---------------- ----------------
See official documentation [on basic concept](https://github.com/os-autoinst/openQA/blob/master/docs/GettingStarted.asciidoc), [test development (including API specification)](https://github.com/os-autoinst/openQA/blob/master/docs/WritingTests.asciidoc), [needles specification](https://github.com/os-autoinst/os-autoinst/blob/master/doc/needles.txt) and [supported variables for backend](https://github.com/os-autoinst/os-autoinst/blob/master/doc/backend_vars.asciidoc). See See official documentation [on basic concept](https://github.com/os-autoinst/openQA/blob/master/docs/GettingStarted.asciidoc),
[test development (including API specification)](https://github.com/os-autoinst/openQA/blob/master/docs/WritingTests.asciidoc),
[needles specification](https://github.com/os-autoinst/os-autoinst/blob/master/doc/needles.txt) and
[supported variables for backend](https://github.com/os-autoinst/os-autoinst/blob/master/doc/backend_vars.asciidoc). See
[this example repo](https://github.com/os-autoinst/os-autoinst-distri-example) on how tests should be structured. [this example repo](https://github.com/os-autoinst/os-autoinst-distri-example) on how tests should be structured.
In short, since OpenQA uses only one entrypoint for all tests (`main.pm`), we have decided to utilize ### main.pm modular architecture
this feature and make tests modular. It means that basic passing through `main.pm` (without any variables set) Since OpenQA uses only one entrypoint for all tests (main.pm), we have decided to utilize
results in most basic installation test executed. Developer can then customize it with additional variables this feature and make tests modular. It means that basic passing through main.pm (without any variables set)
results in most basic installation test executed. Developer can customize it with additional variables
(for example by setting `PACKAGE_SET=minimal` to do installation only with minimal package set). (for example by setting `PACKAGE_SET=minimal` to do installation only with minimal package set).
Make your test modular, so that it utilizes `_boot_to_anaconda()` and `_do_install_and_reboot()` Fedora installation (and consequently main.pm) consists of several parts:
tests (that are loaded automatically). Break your test into smaller parts, each dealing with one
specific feature (e. g. partitioning, user creation...) and add their loading into `main.pm` based 1. booting into Anaconda or booting live image and starting Anaconda
on reasonable variable setting (so they can be used in other tests also).
Since there isn't much variation between tests in this step, we have developed universal `_boot_to_anaconda.pm`
test that is loaded automatically each time except when `ENTRYPOINT` or `UPGRADE` is set (see VARIABLES.md).
To customize this step, you can set following variables:
- `GRUB` is appended to kernel line before boot. You can set for example `inst.updates` here.
- If `KICKSTART` is set, this part of installation ends here (program doesn't wait for Anaconda to appear).
Note that you should set `inst.ks` yourself by setting `GRUB` variable.
- If `LIVE` is set, program waits for desktop to appear and then clicks on "Install to Hard Drive" button.
2. customizing installation by interacting with Anaconda spokes
Most of the differences between tests take place in this part. If you want to add another installation test,
you will probably put your variable checking and test loading here. All tests in this part should start on
Anaconda's main hub and after they done its part, they should go back to Anaconda's main hub so that next
test could be executed. In this phase, universal `_software_selection.pm` test is loaded that handles
selecting what software to install.
To customize this step, you can set following variables:
- Set `PACKAGE_SET` to install required package set on "Software selection spoke" - you have to provide correct needles with the
name of `anaconda_${PACKAGE_SET}_highlighted` and `anaconda_${PACKAGE_SET}_selected`.
- Set `ENCRYPT_PASSWORD` to encrypt disk, value of this variable is used as an actual password.
3. installing Fedora and waiting for Fedora to reboot
After all customizations are finished, `_do_install_and_reboot.pm` test is automatically loaded.
It starts installation, creates user and sets root password when required, waits for installation
to finish and reboots into installed system. Only variables that control flow in this part are these:
- `ROOT_PASSWORD` to set root password to this value.
- When set, `USER_LOGIN` and `USER_PASSWORD` are used to create user in Anaconda.
4. post-install phase
After installation is finished and installed system is fully booted, you can run additional tests
as checks that installed system has correct attributes - that correct file system is used, that
RAID is used etc.
Make your test modular, so that it utilizes `_boot_to_anaconda.pm`, `_software_selection.pm` and
`_do_install_and_reboot.pm` tests (that are loaded automatically). Break your test into smaller parts,
each dealing with one specific feature (e. g. partitioning, user creation...) and add their loading
into main.pm based on reasonable variable setting (so they can be used in other tests also).
### Test inheritance ### Test inheritance
Your test can inherit from `basetest`, `fedorabase`, `installedtest` or `anacondatest`. Your test can inherit from `basetest`, `fedorabase`, `installedtest` or `anacondatest`.
* `basetest` is basic class provided by os-autoinst - it has empty `post_fail_hook()` and doesn't set any flags. - `basetest` is basic class provided by os-autoinst - it has empty `post_fail_hook()` and doesn't set any flags.
* `fedorabase` doesn't neither set flags nor does anything in `post_fail_hook()`, but it provides basic functions - `fedorabase` doesn't neither set flags nor does anything in `post_fail_hook()`, but it provides basic functions
that will be useful during testing Fedora, like `console_login()` or `boot_to_login_screen()`. It should be used that will be useful during testing Fedora, like `console_login()` or `boot_to_login_screen()`. It should be used
when no other, more specific class can be used. when no other, more specific class can be used.
* `anacondatest` should be used in tests where Anaconda is running. It uploads Anaconda logs (for example - `anacondatest` should be used in tests where Anaconda is running. It uploads Anaconda logs (for example
`anaconda.log` or `packaging.log`) in `post_fail_hook()`. It also provides convenient methods for Anaconda `anaconda.log` or `packaging.log`) in `post_fail_hook()`. It also provides convenient methods for Anaconda
like `select_disks()`. like `select_disks()`.
* `installedtest` should be used in tests that are running on installed system (either in postinstall phase - `installedtest` should be used in tests that are running on installed system (either in postinstall phase
or in upgrade tests). It uploads `/var/log` in `post_fail_hook()`. or in upgrade tests). It uploads `/var/log` in `post_fail_hook()`.
### Test development checklist ### New test development workflow
1. Select test from [this document](https://bitbucket.org/rajcze/openqa_fedora_tools/src/develop/PhaseSeparation.md) or from [phabricator page](https://phab.qadevel.cloud.fedoraproject.org/maniphest/?statuses=open%28%29&projects=PHID-PROJ-epofbmazit3u2rndqccd#R) 1. Select test from [this document](https://bitbucket.org/rajcze/openqa_fedora_tools/src/develop/PhaseSeparation.md) or from
[phabricator page](https://phab.qadevel.cloud.fedoraproject.org/maniphest/?statuses=open%28%29&projects=PHID-PROJ-epofbmazit3u2rndqccd#R)
2. Put each part of your test as a separate file into `tests/` directory, reimplementing `run()` method 2. Put each part of your test as a separate file into `tests/` directory, reimplementing `run()` method
and `test_flags()` method, inheriting from one of the classes mentioned above. and `test_flags()` method, inheriting from one of the classes mentioned above.
3. Set correct variables (so that all test parts you have made are executed) in [WebUI -> Test suites](https://localhost:8080/admin/test_suites). 3. Set correct variables (so that all test parts you have made are executed) in [WebUI -> Test suites](https://localhost:8080/admin/test_suites).
@ -43,6 +91,7 @@ and `test_flags()` method, inheriting from one of the classes mentioned above.
5. Run test (see [openqa_fedora_tools repository](https://bitbucket.org/rajcze/openqa_fedora_tools)). 5. Run test (see [openqa_fedora_tools repository](https://bitbucket.org/rajcze/openqa_fedora_tools)).
6. Create needles (images) by using interactive mode and needles editor in WebUI. 6. Create needles (images) by using interactive mode and needles editor in WebUI.
7. Add new Job template and Test suite into `templates` file. 7. Add new Job template and Test suite into `templates` file.
8. Add new Test suite and Test case into [`conf_test_suites.py`](https://bitbucket.org/rajcze/openqa_fedora_tools/src/develop/tools/openqa_trigger/conf_test_suites.py) file in openqa_fedora_tools repository. 8. Add new Test suite and Test case into [`conf_test_suites.py`](https://bitbucket.org/rajcze/openqa_fedora_tools/src/develop/tools/openqa_trigger/conf_test_suites.py)
file in openqa_fedora_tools repository.
9. Mark your test in PhaseSeparation.md as done. 9. Mark your test in PhaseSeparation.md as done.
10. Open differential request via phabricator. 10. Open differential request via phabricator, set openqa_fedora as a project and repository.

View File

@ -17,7 +17,7 @@ These variables control settings of underlying virtual machine where tests runs
| `BIOS` | filename | `ovmf-x86_64-ms.bin` for `x86_64` UEFI, not set otherwise | set different BIOS | | `BIOS` | filename | `ovmf-x86_64-ms.bin` for `x86_64` UEFI, not set otherwise | set different BIOS |
| `BOOTFROM` | characters (see man qemu, `-boot order=` option) | not set | boot from different medium than CD | | `BOOTFROM` | characters (see man qemu, `-boot order=` option) | not set | boot from different medium than CD |
| `CDMODEL` | see `qemu-kvm -device help` | not set/Qemu default | type of device for CD | | `CDMODEL` | see `qemu-kvm -device help` | not set/Qemu default | type of device for CD |
| `HDDMODEL` | see `qemu-kvm -device help` | `virtio-blk` | type of device for HDD | | `HDDMODEL` | see `qemu-kvm -device help` (e. g. PATA = `id-hd`, SATA = `ide-hd,bus-ahci0.0`, SCSI = `virtio-scsi-pci`) | `virtio-blk` | type of device for HDD |
| `HDDSIZEGB` | integer | `10` | size (in GBs) for disks that are created automatically | | `HDDSIZEGB` | integer | `10` | size (in GBs) for disks that are created automatically |
| `HDD_$i` (`HDD_1, HDD_2`, ...) | filename | not set | attach additional HDD to VM | | `HDD_$i` (`HDD_1, HDD_2`, ...) | filename | not set | attach additional HDD to VM |
| `ISO` | filename | not set | attach CD drive with ISO inserted | | `ISO` | filename | not set | attach CD drive with ISO inserted |