On Tue, Jul 12, 2022 at 02:44:36PM +0200, Erik Skultety wrote:
Currently we don't have much information on how testing is done in libvirt and the little we have is scattered among multiple files. This patch creates a common landing page containing all important bits about testing in libvirt, providing links to respective sections which deserve their own articles.
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- docs/meson.build | 1 + docs/testing.rst | 176 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 177 insertions(+) create mode 100644 docs/testing.rst
diff --git a/docs/meson.build b/docs/meson.build index 0c7c54a75f..6d61e18385 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -105,6 +105,7 @@ docs_rst_files = [ 'submitting-patches', 'support', 'testapi', + 'testing', 'testsuites', 'testtck', 'uri', diff --git a/docs/testing.rst b/docs/testing.rst new file mode 100644 index 0000000000..af0f334633 --- /dev/null +++ b/docs/testing.rst @@ -0,0 +1,176 @@ +======= +Testing +======= + +.. contents:: + +Different types of tests are available to libvirt developers for testing a +given libvirt release. + +Unit tests +---------- + +The unit test suite present in the source code is mainly used to test our +XML parser/formatter, QEMU command line generator, QEMU capabilities probing, +etc. It is run by developers before submitting patches upstream and is +mandatory to pass for any contribution to be accepted upstream. One can run +the test suite in the source tree with the following + +:: + + make check (libvirt 6.6.0 and older) +
IMHO we can ignore documenting such old releases.
+:: + + ninja test (libvirt 6.7.0 and newer) + +
+Docker Prerequisites +~~~~~~~~~~~~~~~~~~~~ + +Install "docker" with the system package manager and start the Docker service +on your development machine, then make sure you have the privilege to run +Docker commands. Typically it means setting up passwordless ``sudo docker`` +command or login as root. For example: + +.. code:: + + $ sudo yum install docker
s/yum/dnf/ and perhaps also 'install -y'
+ $ # or `apt-get install docker` for Ubuntu, etc. + $ sudo systemctl start docker + $ sudo docker ps + +The last command should print an empty table, to verify the system is ready. + +An alternative method to set up permissions is by adding the current user to +"docker" group and making the docker daemon socket file (by default +``/var/run/docker.sock``) accessible to the group: + +.. code:: + + $ sudo groupadd docker + $ sudo usermod $USER -a -G docker + $ sudo chown :docker /var/run/docker.sock + +Note that any one of above configurations makes it possible for the user to +exploit the whole host with Docker bind mounting or other privileged +operations. So only do it on development machines. + +Podman Prerequisites +~~~~~~~~~~~~~~~~~~~~ + +Install "podman" with the system package manager. + +.. code:: + + $ sudo dnf install podman
Also 'install -y'
+ $ podman ps + +The last command should print an empty table, to verify the system is ready.
Given it has much simpler setup, and doesn't open a local root shell I'd suggest we document podman first, and explicitly recommend its usage, over docker. With regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|