test/cfg2cmd/README.adoc

   1 QemuServer Config 2 Command Test
   2 ================================
   3 Thomas Lamprecht <t.lamprecht@proxmox.com>
   4
   5 Overview
   6 --------
   7
   8 This is a relatively simple configuration to command test program.
   9 It's main goals are to better enforce stability of commands, thus reducing
  10 the likelihood that, for example, a migration breaking change which forgot to
  11 bump/check the KVM/QEMU version, slips through
  12
  13 Further you get a certain regression and functional test coverage. You get a
  14 safety net against breaking older or not often (manual) tested setups and
  15 features.
  16
  17 NOTE: The safety net is only as good as the test count *and* quality.
  18
  19
  20 Test Specification
  21 ------------------
  22
  23 A single test consists of two files, the input VM config `FILE.conf` and the
  24 expected output command `FILE.conf.cmd`
  25
  26 Input
  27 ~~~~~
  28
  29 The `FILE.conf` are standard Proxmox VE VM configuration files, so you can just
  30 copy over a config file from `/etc/pve/qemu-server` to add a configuration you
  31 want to have tested.
  32
  33 Output
  34 ~~~~~~
  35
  36 For the expected output `FILE.conf.cmd` we check the KVM/QEMU command produced.
  37 As a single long line would be pretty hard to check for (problematic) changes
  38 by humans, we use a pretty format, i.e., where each key value pair is on it's
  39 own line. With this approach we can just diff expected and actual command and
  40 one can pin point pretty fast in which component (e.g., net, drives, CPU, ...)
  41 the issue is, if any. Such an output would look like:
  42
  43 ----
  44 /usr/bin/kvm \
  45   -id 101 \
  46   -name vm101 \
  47   ...
  48 ----
  49
  50 TIP: If the expected output file does not exist we have nothing to check, but
  51 for convenience we will write it out. This should happen from clean code, and
  52 the result should not get applied blindly, but only after a (quick) sanity
  53 check.
  54
  55
  56 Environment
  57 ~~~~~~~~~~~
  58
  59 It makes sense to have a stable and controlled environment for tests, thus you
  60 one can use the 'description' in VM configurations to control this. The
  61 description consists of all lines beginning with a '#' as first non-whitespace
  62 character. Any environment variable follows the following format:
  63
  64 ----
  65 # NAME: VALUE
  66 ... rest of config...
  67 ----
  68
  69 There are the following variables you can control:
  70
  71 * *TEST*: a one line description for your test, gets outputted one testing and
  72   should described in a short way any specialty about this specific test,
  73   i.e., what does this test wants to ensure.
  74
  75 * *QEMU_VERSION*: the version we fake for this test, if not set we use the
  76   actual one installed on the host.
  77
  78 * *HOST_ARCH*: the architecture we should fake for the test (aarch64 or x86_64),
  79   defaults to `x86_64` to allow making this optional and still guarantee
  80   stable tests
  81
  82 The storage environment is currently hardcoded in the test code, you can
  83 extend it there if it's needed.
  84
  85 // vim: noai:tw=78