[libvirt PATCH 04/10] docs: Provide an article on testing

[Daniel P. Berrangé]

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 at 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 :|