.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "LIFT.YAML" 1 "" "2.5.0" "Lift Manual"
.SH NAME
lift.yaml \- Define a Lift test suite
.SH DESCRIPTION
.sp
Lift provides an integration/functional test platform which handle
\fBexecutable\fP tests easily and generically.
.sp
\fIlift.yaml\fP files are used to define a test suite.
Such a file is written in YAML (\fI\%http://yaml.org/\fP) and support 3 root sections
types: \fBsettings\fP, \fBlocal tests\fP and \fBremote tests\fP\&. These are documented
further below in this documentation.
.sp
A Lift test suite is composed of at least one \fIlift.yaml\fP file but it is often
a folder hierarchy with one \fIlift.yaml\fP file at each level.
.sp
Such a hierarchy is useful to define more specialized sub\-suites (eg. one for
basic functionalities, one for performances...). Each sub\-suite has its own
\fIlift.yaml\fP and can be run individually.
.sp
Settings defined on a \fIlift.yaml\fP file are inherited in sub\-suites.
Sub\-suites can override inherited settings if they need to.
.SH SETTINGS DEFINITION
.sp
This section is used to define remotes machines that will be used for remote
tests and to define environment variables that will be passed to tests.
.sp
Environment variables can be overridden for each test individually in their
definition.
.sp
The \(aqsettings\(aq section has to be defined at the root of the \fIlift.yaml\fP file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
settings:
    # The \(aqdefine\(aq keyword followed by the remote name
    define my_remote:
        host: localhost  # mandatory
        username: root  # mandatory
        password: foobar  # optional (if ssh keys are set properly)
    define my_other_remote:
        host: localhost
        username: not_root
        password: foobar
    # These will be transmitted to the test commands
    # They can be used as a way to pass common settings around
    environment:
        MY_ENV_VAR1: foo
        MY_ENV_VAR2: bar
.ft P
.fi
.UNINDENT
.UNINDENT
.SH LOCAL TEST DEFINITION
.sp
Each test is represented by a single section at the root of the \fIlift.yaml\fP
file. Here is an example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# the \(aqtest\(aq keyword followed by the test name
test my_test_name:
    command: "./my_test_executable \-\-my\-arg"  # mandatory
    return code: 0  # optional (default to 0)
    timeout: 10  # optional, in seconds (no timeout by default)
    environment:  # optional
        MY_VAR: 42  # may override an already defined variable
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a test timeouts, it will return 124. You can therefore test that a command
does timeout by setting the \(aqreturn code\(aq value to 124.
.sp
The actual environment used by a test is computed in the following order:
environment defined in higher level \fIlift.yaml\fP files (inheritance), then
the environment defined in the current \fIlift.yaml\fP file and finally the
environment defined in the test itself.
.sp
The \(aqcommand\(aq can be an absolute path, a path relative to the current
\fIlift.yaml\fP position or a system command (like ping, curl...)
.SH REMOTE TEST DEFINITION
.sp
Each remote test is represented by a single section at the root of the
\fIlift.yaml\fP file.
Please also refer to the local test definition documentation, as all
options are reused in the same way for remote tests.
Here is an example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# A known remote name followed by the \(aqtest\(aq keyword and the test name
# This defines a test that will be ran on my_remote.
my_remote test my_remote_test_name:
    command: "sh test/test.sh \-\-my\-arg"
    return code: 0
    timeout: 2
    # List files and folders that will be uploaded to the remote
    # before running the test.
    resources:
        \- test/
    environment:
        MY_VAR: content
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To be known, a remote has to be defined either in a higher level \fIlift.yaml\fP
file (inheritance) or in the current \fIlift.yaml\fP or directly via the
\fB\-\-remote\fP option of the \fBlift\fP command line.
.sp
Files resources are uploaded "flatly" whereas folders keep their structure.
Lift will take care of deleting all resources from the remote after the test is
over.
.sp
The command will be executed in a temporary directory that will be created on
the remote. Resources will be put in this directory, so you can use relative
paths to them in your command/executable.
.SH FULL TEST SUITE EXAMPLE
.sp
The \fIexample\fP folder at the root of the Lift sources contains a fully commented
example of a Lift test suite, which can also be used as a functional test suite
for Lift itself.
.sp
On Debian systems, the \fIexample\fP folder can be found in
\fI/usr/share/doc/lift/example\fP\&.
.SH SEE ALSO
.sp
For the command line utility, see \fBlift\fP (1)
.SH AUTHOR
Written an maintained by Nicolas Delvaux <contact@nicolas-delvaux.org>
.SH COPYRIGHT
GPL2+
.\" Generated by docutils manpage writer.
.