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@xxxxxxxxxx> > --- > 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 :|
