.\"                                      Hey, EMACS: -*- nroff -*-
.\" (C) Copyright #YEAR# #USERNAME# <#EMAIL#>,
.\"
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH ASTERISK 1 "2014-08-29"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
.\" respectively.
.SH NAME
asterisk\-tests\-run \- run tests for the asterisk-testsuite
.SH SYNOPSIS
.B asterisk\-tests\-run [\fIoptions\fB]

The Asterisk test suite is a set of tests to check various versions of
the Asterisk PBX software. The command
.B asterisk\-tests\-run
runs all the tests, some of them (selectable by tags), or just a single
test.

The test suite will detect if the test can run on the system (if it has
the required software to run the test, if it has the required version of
Asterisk and if Asterisk is built with the required configuration) and
if so, will run it.

This command is mostly a wrapper around
.B runtests.py
of the asterisk\-testsuite. This man page documents runtests.py itself
except where explicitly mentioned.

.SH OPTIONS
.SS Test Selection
By default all the tests are selected.

.TP
.B \-t, \-\-test=\fItest
Only run the selected test. The name of the test is the name of the
subdirectory including the leading "tests/".

.TP
.B \-g, \-\-tag=\fItag
Specify tag by which to select tests. If option is used more than once,
all tests matching any of the tags will be selected.

.TP
.B \-l, \-\-list
Don't run any test. Just list all of them. Note: the list is long.

.TP
.B \-L, \-\-list\-tags
Don't run any test. Just list all the tags.

.TP
.B \-h, \-\-help
Show summary of options without emitting an error message.

.SS Other Options
.TP
.B \-v, \-\-version=\fIversion-string
Provide an explicit version of Asterisk to be tested, in case it cannot
be probed successfully.

.TP
.B \-n, \-\-dry\-run
Don't run. Just print the test should be run (or why tests would not be
run).

.TP
.B \-H \-\-hide\-skipped
Don't print tests that were not run.

.TP
.B \-o \-\-output\-dir=\fIdirectory
An internal option. Please don't use explicitly with asterisk\-tests\-run.
Directs runtests where to write its output file
(asterisk-test-suite-report.xml). The script directs it to
/var/lib/asterisk-testsuite .

.TP
.B \-c \-\-extra\-config=\fIdirectory
Pass extra configuration settings from \fIdirectory\fB/config.yaml\fP.
Most settings are not read from that file. Only test exclusions (in
additions to tests getting excluded in the the main config.yaml of the
tests directory).

.SH EXAMPLES
.TP
asterisk\-tests\-run
Just run all the tests.

.TP
asterisk\-tests\-run \-g SIP \-g AGI
Run both SIP and AGI tests.

.TP
asterisk\-tests\-run \-t tests/agi/exit_status
Run one specific test.

.TP
asterisk\-tests\-run \-\-list
List all the tests.

.TP
asterisk\-tests\-run \-\-dry\-run
An even more verbose list

.TP
asterisk\-tests\-run \-\-extra\-config /usr/share/asterisk/test
Takes extra settings from file /usr/share/asterisk/test/test-config.yaml

.SH SEE ALSO
.BR asttest (1)