[[!meta title="Test suite installation and setup"]]

Here's how to set up an environment to run our automated test suite.
Alternatively, you way want to use the `tails::tester` class from the
[[!tails_gitweb_repo puppet-tails]] Puppet module.

Once you have a working environment, see [[test/usage]].

[[!toc levels=2]]

Install dependencies
====================

First of all, one needs a Debian Jessie system with:

 * the `non-free` APT component enabled;
 * the official backports repository configured.

The following packages are necessary on Debian Jessie:

    echo -e "Package: *\nPin: release o=Debian,n=jessie\nPin-Priority: 990" \
        > /etc/apt/preferences.d/Debian_jessie && \
    apt update && \
    apt install \
        cucumber \
        devscripts \
        dnsmasq-base \
        gawk \
        git \
        i18nspector \
        libav-tools \
        libcap2-bin \
        libsikuli-script-java \
        libvirt-clients \
        libvirt-daemon-system \
        libvirt-dev \
        libvirt0 \
        obfs4proxy \
        openssh-server \
        ovmf \
        pry \
        python-jabberbot \
        python-potr/jessie-backports \
        qemu-kvm/jessie-backports \
        qemu-system-common/jessie-backports \
        qemu-system-x86/jessie-backports \
        qemu-utils/jessie-backports \
        ruby-guestfs \
        ruby-json \
        ruby-libvirt \
        ruby-net-irc \
        ruby-packetfu \
        ruby-rb-inotify \
        ruby-rjb \
        ruby-rspec \
        ruby-test-unit \
        seabios \
        tcpdump/jessie-backports \
        tor/jessie-backports \
        unclutter \
        virt-viewer \
        x11vnc \
        xtightvncviewer \
        xvfb \
        && \
    service libvirtd restart
        
Other requirements
==================

Synchronized clock
------------------

The system running the test suite needs an accurate clock since we
sync the clock from the host to the Tails guest after a background
snapshot restore to appease Tor.

You might want to install `ntp` or your favorite time synchronization
tool for this.

File permissions
----------------

The user that runs QEMU (via libvirt) needs read-access at least to
the content of `features/misc_files/` in the Git checkout.

AppArmor tweaks
---------------

If libvirt has the `apparmor` security driver enabled:

* you may need to add the `/tmp/TailsToaster/TailsToasterStorage/*
  rw,` line to `/etc/apparmor.d/libvirt/TEMPLATE.qemu`, in the
  `profile LIBVIRT_TEMPLATE` section;
* you may hit various problems, such as denied access to
  `/usr/share/ovmf/OVMF.fd`; all such known problems are (as of
  2015-08-12) on their way for being fixed upstream in libvirt.
  Running a recent libvirt may help.

Special use cases
=================

Access the system under test with VNC
-------------------------------------

If you're running the test suite in a nested environnement, install
xtightvncviewer on the bare metal level-0 host. Then you can use vncviewer's
`-via` option so that it automatically setup a ssh tunnel to your first level
test suite domain for you and display the Tails VM. E.g.
where `$DISPLAY` is the display given to you by `run_test_suite` (often 0):

    vncviewer -viewonly -via user@level0 localhost:$DISPLAY

Running the test suite as a non-root user
-----------------------------------------

<div class="note">
This section may not be in tested and working shape.
</div>

This is entirely possible, but there's some additional configuration
required. Run the following as `root`:

    addgroup tcpdump
    dpkg-statoverride --update --add root tcpdump 754 /usr/sbin/tcpdump
    setcap CAP_NET_RAW+eip /usr/sbin/tcpdump
    adduser $USER tcpdump
    adduser $USER libvirt
    adduser $USER libvirt-qemu

It's important to run `setcap` after `dpkg-statoverride` since the
latter deletes all capabilities. Unfortunately the `setcap` command
has to be rerun for that reason everytime the `tcpdump` package is
updated until [[!debbug 662845]] is fixed.

Running these commands will add some interesting capabilities to
`$USER`, so you may want to do this for a dedicated user separate from
your normal user. In that case (and if you run the tests as root) the
`--view` option won't work unless you grant `$USER` access to your
display via `xhost +SI:localhost:$USER`. Alternatively you can use the
`--vnc-server-only` option and manually connect to the VNC server with
your normal user. Just make sure the VNC viewer is in view-only mode
(e.g. `xtightvncviewer --view-only ...`) in order to not interfere
with the testing session.
