test/

README

LXD tests

For a description of where and how LXD is tested, please refer to the overview document.

How to run

To run all tests, including the Go tests, run from repository root:

sudo -E make check

To run only the integration tests, run from the test directory:

sudo -E ./main.sh

Environment variables

Name	Default	Description
LXD_BACKEND	dir	What backend to test against (btrfs, ceph, dir, lvm, zfs, or random)
LXD_BACKENDS	LXD_BACKEND	Space-delimited list of backends to run test against. Accepts fast (btrfs or dir), fasts (btrfs and dir) and all (see the list in LXD_BACKEND)
LXD_CEPH_CLUSTER	ceph	The name of the ceph cluster to create osd pools in
LXD_CEPH_CEPHFS	cephfs	Enables the CephFS tests using the specified cephfs filesystem for cephfs pools
LXD_CEPH_CEPHOBJECT_RADOSGW	""	Enables the Ceph Object tests using the specified radosgw HTTP endpoint for cephobject pools
LXD_VERBOSE	""	Run lxd, lxc and the shell in verbose mode (used in CI; less verbose than LXD_DEBUG)
LXD_DEBUG	""	Run lxd, lxc and the shell in debug mode (very verbose)
LXD_INSPECT	0	Set to 1 to start an inspection shell in the test environment on failure
LXD_LOGS	""	Path to a directory to copy all the LXD logs to
LXD_REPEAT_TESTS	1	Number of times to repeat test(s)
LXD_RANDOMIZE_TESTS	0	Randomize the order of tests in a group
LXD_SKIP_TESTS	""	Space-delimited list of test names to skip
LXD_TEST_IMAGE	"" (busybox test image)	Path to an image tarball to use instead of the default busybox image
LXD_TEST_LIVE_MIGRATION_ON_THE_SAME_HOST	""	When set to true, LXD ignores EBUSY errors during same-host live migration when unmounting a source volume that is already mounted on the destination instance.
LXD_TMPFS	0	Sets up a tmpfs for the whole testsuite to run on (fast but needs memory)
LXD_NIC_SRIOV_PARENT	""	Enables SR-IOV NIC tests using the specified parent device
LXD_IB_PHYSICAL_PARENT	""	Enables Infiniband physical tests using the specified parent device
LXD_IB_SRIOV_PARENT	""	Enables Infiniband SR-IOV tests using the specified parent device
LXD_NIC_BRIDGED_DRIVER	""	Specifies bridged NIC driver for tests (either native or openvswitch, defaults to native)
LXD_REQUIRED_TESTS	""	Space-delimited list of test names that must not be skipped if their prerequisites are not met
LXD_VM_TESTS	1	Enables tests using VMs and the on-demand installation of the needed tools

Recommendations

sub_test usage

Use sub_test to label meaningful phases within a test and make logs easier to scan. Prefer a small number of focused sub-tests over excessive nesting. Use sub_test before a logical group of commands that verifies a specific expected behavior for a bug fix or feature. Comments within the sub-test block are appropriate to explain why specific commands are used, any setup or initial configuration, and other intent that isn't obvious from the commands.

Good:

sub_test "Verify intended behavior X"
...
sub_test "Verify intended behavior Y"
...

echo context

Prefer sub_test labels and concise comments for context instead of adding echo statements. Use echo only when you need to debug flaky behavior.

Expected failure

If a command is expected to fail, special care needs to be used in testing.

Bad:

set -e
...

! cmd_should_fail

some_other_command

Good:

set -e

! cmd_should_fail || false

some_other_command

Best:

set -e

if cmd_should_fail; then
  echo "ERROR: cmd_should_fail unexpectedly succeeded, aborting" >&2
  exit 1
fi

some_other_command

In the "bad" example, if the command unexpectedly succeeds, the script won't abort because bash ignores set -e for compounded commands (! cmd_should_fail).

The "good" example works around the problem of compound commands by falling back to executing false in case of unexpected success of the command.

The "best" example also works around the problem of compound commands but in a very intuitive and readable form, albeit longer.

This odd behavior of `set -e` with compound commands does not apply inside `[]`.

```sh
set -e
# Does the right thing of failing if the file unexpectedly exist
[ ! -e "should/not/exist" ]
```

However, note that in the above example, if the `!` is moved outside of the `[]`, it would also warrant a ` || false` fallback.

For error message assertions, prefer single-quoted strings so error text with " does not require escaping and the comparisons stay readable.