From 82c7b8ffc84124e8dc59793e1943e62014980027 Mon Sep 17 00:00:00 2001 From: Sebastian Mitterle Date: Wed, 19 Feb 2020 19:46:32 +0100 Subject: [PATCH] Update Getting Started 1. Avocado doc has been restructured: fix broken links 2. Give more priority to pip installation: a. It's the primary installation method for Avocado (s. doc https://avocado-framework.readthedocs.io/en/latest/guides/user/chapters/installing.html "Avocado is primarily written in Python, so a standard Python installation is possible and often preferable. You can also install from your distro repository, if available." etc.) b. Pip installation is available on more environments. c. Whoever wants to develop/debug test cases is better off with pip installation. 3. Recommend to use the same installation method for both plugin and main program: a. Mixing both methods can lead to issues due to version incompatibility and command availability. 4. Add python-devel as dependency: I got installation error from dependency netifaces (Python.h: No such file or directory) 5. Add a note that test backend related progrmas should be available on target system in order to list test cases. 6. As consequence of GetStartedGuide: Add virsh to recommended programs for qemu test backend because Networking is usually done using libvirtd's virbr0 - s. https://avocado-vt.readthedocs.io/en/latest/Networking.html A user following the GetStartedGuide and gets to the point where they randomly chose any test, e.g. `lvm.lvm_create` for execution from `avocado list --vt-type qemu` will just see "ERROR: Can't add interface ... to bridge virbr0: there is no bridge in the system." It's not enough for them to just add a bridge of that name, so it can become quite tedious. By having the virsh already as a recommended program the user can at least try install it which would then automatically set up the default network with correct bridge. --- README.rst | 2 +- docs/source/GetStartedGuide.rst | 52 +++++++++++++++++++++------------ virttest/bootstrap.py | 2 +- 3 files changed, 36 insertions(+), 20 deletions(-) diff --git a/README.rst b/README.rst index 2c0f4d1adf..73920e2888 100644 --- a/README.rst +++ b/README.rst @@ -11,7 +11,7 @@ Gettings started with Avocado First of all, make sure you have Avocado itself installed. You can check the Avocado online documentation at: -http://avocado-framework.readthedocs.org/en/latest/GetStartedGuide.html#installing-Avocado +https://avocado-framework.readthedocs.io/en/latest/guides/user/chapters/installing.html Getting started with Avocado-VT =============================== diff --git a/docs/source/GetStartedGuide.rst b/docs/source/GetStartedGuide.rst index 3c14766c47..55eeecee65 100644 --- a/docs/source/GetStartedGuide.rst +++ b/docs/source/GetStartedGuide.rst @@ -6,24 +6,22 @@ Getting Started The first step towards using Avocado-VT is, quite obviously, installing it. -Installing Avocado-vt +Installing Avocado-VT ===================== -Avocado-vt is an Avocado plugin, therefor you are going to need both in -order to be able to execute the tests. Usually the packaging mechanism -should take care of the deps, but when package is not available for -your distro, you need to start by installing Avocado, steps are -`described here `__. +Avocado-VT is an Avocado plugin, therefore you are going to need both in +order to be able to execute the tests. -Fedora and Red Hat Enterprise Linux ------------------------------------ +Both are primarily written in Python, so a standard Python installation is +possible and often preferable. -Installing Avocado-VT on Fedora or Enterprise Linux is a matter of -installing the `avocado-plugins-vt` package. Install it with:: +If you just want to use the plugin to run tests you might prefer to use +packages from your system's package manager if available; this way non-python +dependencies, esp. Avocado, are also taken care of automatically. - $ yum install avocado-plugins-vt +You can find more details about the Avocado installation +`here `__. -Which takes care of all the dependencies (python and non-python ones). Installing via PIP ------------------ @@ -32,9 +30,9 @@ Pip is useful when it comes to python dependencies, but it fails in non-python ones. List of non-python requirements based on Fedora package names is:: - $ dnf install xz tcpdump iproute iputils gcc glibc-headers nc git python-netaddr + $ dnf install xz tcpdump iproute iputils gcc glibc-headers nc git python-netaddr python-devel -Then you can get Avocado-vt via pip:: +Then you can get Avocado-VT via pip:: $ pip install git+https://github.com/avocado-framework/avocado-vt @@ -48,12 +46,22 @@ It's recommended to use ``pip`` even for local install as it treats requirements differently and the use of ``python setup.py install`` might fail. -Using Avocado-vt from sources +Installing via system package manager +------------------------------------- + +Installing Avocado-VT on Fedora or Enterprise Linux is a matter of +installing the `avocado-plugins-vt` package. Install it with:: + + $ yum install avocado-plugins-vt + +Which takes care of all the dependencies (python and non-python ones). + +Setup Avocado-VT with sources ----------------------------- -If you intend use avocado from sources, clone it into the same parent dir -as Avocado sources and use ``make link`` from the Avocado sources dir. -Details about this can be found `here `__. +If you intend use avocado from sources, clone it into the same parent directory +as Avocado sources and use ``make link`` from the Avocado sources directory. +Details about this can be found `here `__. .. _run_bootstrap: @@ -96,6 +104,11 @@ The output should be similar to:: If there are missing requirements, please install them and re-run `vt-bootstrap`. +.. note:: Recommended programs might be needed for Avocado to correctly + recognize test cases for your test backend or for test cases + to run correctly. + + First steps with Avocado-VT =========================== @@ -127,6 +140,9 @@ This should list a large amount of tests (over 1900 virt related tests):: SIMPLE: 3 VT: 1906 +.. note:: If no test cases are listed make sure you installed recommended + programs on your system, s. "Bootstrapping Avocado-VT". + Now let's run a virt test:: $ avocado run type_specific.io-github-autotest-qemu.migrate.default.tcp diff --git a/virttest/bootstrap.py b/virttest/bootstrap.py index 7406f750f1..7b533615c8 100644 --- a/virttest/bootstrap.py +++ b/virttest/bootstrap.py @@ -26,7 +26,7 @@ basic_program_requirements = ['xz', 'tcpdump', 'nc', 'ip', 'arping'] recommended_programs = {'qemu': [('qemu-kvm', 'kvm'), ('qemu-img',), - ('qemu-io',)], + ('qemu-io',), ('virsh',)], 'spice': [('qemu-kvm', 'kvm'), ('qemu-img',), ('qemu-io',)], 'libvirt': [('virsh',), ('virt-install',),