#
# This file and its contents are supplied under the terms of the
# Common Development and Distribution License ("CDDL"), version 1.0.
# You may only use this file in accordance with the terms of version
# 1.0 of the CDDL.
#
# A full copy of the text of the CDDL should have accompanied this
# source.  A copy of the CDDL is also available via the Internet at
# http://www.illumos.org/license/CDDL.
#

#
# Copyright 2018, Joyent, Inc.
#

I) Introduction

The procedure to run the illumos tests under SmartOS is unlike that for
other distributions because of the zone-centric nature of the distribution,
and because there is no built-in package management for the global zone.

This Readme assumes you will run the tests in the global zone, as root.
Although it is possible to run some of the tests within a non-global zone, as a
user configured within that zone, that approach is not described here.

Some test suites, such as the ZFS tests, assume there are available disks to
use for the test run. For more information on running the ZFS tests, see II.4).

II) Setup to Run the Tests

1) The tests currently require python27 to run, so you need to install this in
   the global zone. The easiest way to do this is with pkgsrc using the
   following procedure:

   a) Get a copy of the following bootstrap tarball onto the test machine:
      https://pkgsrc.joyent.com/packages/SmartOS/bootstrap/bootstrap-2014Q4-multiarch.tar.gz

   b) Install the bootstrap tarball:
      # gzcat bootstrap-2014Q4-multiarch.tar.gz | (cd /; tar -xpf -)

   c) Install python27:
      pkgin in python27

2) You need to get the tests from your build machine onto the test machine's
   global zone. This can be done in whatever way is easiest for you. Here is
   one simple way:

   a) On your build machine, in your fully built smartos-live proto area,
      create a tarball of the test directory:
      % cd proto/opt
      % tar czf ../opt.tgz *


   b) Copy the tarball from the build machine to the test machine running
      SmartOS (the next step assumes you placed the tarball into the /zones
      directory).

3) In the global zone on your test machine, install the tests.

   # cd /opt
   # tar xf /zones/opt.tgz

4) (optional) Running the ZFS tests requires a few additional steps.
   The ZFS test suite must _not_ be run as the root user. Instead we will create
   a new user called 'ztest' that we will use to run the tests.

   a) Make sure the system has three unused 10GB disks. These disks must not be
      associated with an existing zpool.

   b) In preparation for installing 'sudo' and adding a user for the ZFS test
      suite, edit /etc/passwd and /etc/shadow:
      # echo "cyrus:x:100:1::/home/cyrus:/bin/sh" >> /etc/passwd
      # echo "ztest:x:101:1::/home/ztest:/bin/sh" >> /etc/passwd
      # echo "cyrus:*LK*:::::::" >> /etc/shadow
      # echo "ztest:*LK*:::::::" >> /etc/shadow

      Note: The /etc/passwd modifications will not persist after reboot.

   c) sudo and truncate must be installed. They will later be linked into the
      appropriate location by the ZFS test suite.
      # pkgin in sudo
      # pkgin in coreutils # provides truncate

   d) The ztest user must be able to use sudo without a password:
      # echo "ztest ALL=(ALL) NOPASSWD: ALL" >> /opt/local/etc/sudoers

   e) Change to the 'ztest' user and set environment variables. In this example
      DISKS is the list of three unused disks that will be used to run the
      tests. KEEP is a list of zpools that the tests should _not_ destroy:
      # su ztest
      $ export DISKS='c2t1d0 c2t2d0 c2t3d0'
      $ export KEEP='zones'

      Beware that data loss will occur for any data residing on DISKS and
      failure to specify a KEEP pool may also lead to data loss.

III) Run the Tests

Now that setup is complete, you can run the tests using the normal procedure.
For example:

    # /opt/util-tests/bin/utiltest
or
    # /opt/os-tests/bin/ostest
or (as 'ztest' user after 4.e above)
    $ /opt/zfs-tests/bin/zfstest

IV) Running New Tests

During development, if you are creating or updating new tests, you can repeat
steps 2 and 3 as often as necessary to make the new tests available on the test
machine.