From 22664d341b55905b44547958dbe067c3df3c28d7 Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Wed, 20 Aug 2014 08:53:16 -0300 Subject: [PATCH] docs: add initial man page This page is intended as a basic offline aid for new users of avocado. Signed-off-by: Cleber Rosa --- avocado.spec | 9 ++- man/avocado.rst | 171 ++++++++++++++++++++++++++++++++++++++++++++++++ setup.py | 10 +++ 3 files changed, 189 insertions(+), 1 deletion(-) create mode 100644 man/avocado.rst diff --git a/avocado.spec b/avocado.spec index 176ab406..1625d2cd 100644 --- a/avocado.spec +++ b/avocado.spec @@ -6,7 +6,7 @@ License: GPLv2 Group: Development/Tools URL: http://avocado-framework.readthedocs.org/ Source: avocado-%{version}.tar.gz -BuildRequires: python2-devel +BuildRequires: python2-devel, python-docutils BuildArch: noarch Requires: python, python-requests @@ -19,9 +19,12 @@ these days a framework) to perform automated testing. %build %{__python} setup.py build +%{__python2} /usr/bin/rst2man man/avocado.rst man/avocado.1 %install %{__python} setup.py install --root %{buildroot} --skip-build +%{__mkdir} -p %{buildroot}%{_mandir}/man1 +%{__install} -m 0644 man/avocado.1 %{buildroot}%{_mandir}/man1/avocado.1 %files %defattr(-,root,root,-) @@ -30,6 +33,7 @@ these days a framework) to perform automated testing. %config(noreplace)/etc/avocado/settings.ini %{_bindir}/avocado %{python_sitelib}/avocado* +%{_mandir}/man1/avocado.1.gz %package tests Summary: Avocado Test Framework Sample Tests @@ -42,6 +46,9 @@ The set of example tests that are part of the Avocado framework. %{_datadir}/avocado/tests %changelog +* Wed Aug 20 2014 Cleber Rosa - 0.10.1-2 +- Added initial avocado man page + * Tue Aug 12 2014 Lucas Meneghel Rodrigues - 0.10.1-1 - Bugfix release 0.10.1 diff --git a/man/avocado.rst b/man/avocado.rst new file mode 100644 index 00000000..85207959 --- /dev/null +++ b/man/avocado.rst @@ -0,0 +1,171 @@ +:title: avocado +:subtitle: test runner command line tool +:title_upper: AVOCADO +:manual_section: 1 + +SYNOPSIS +======== + +:: + + avocado [-h] [-v] [-V] [--logdir LOGDIR] [--loglevel LOG_LEVEL] + [--plugins PLUGINS_DIR] [--silent] [--vm] + [--vm-hypervisor-uri VM_HYPERVISOR_URI] [--vm-domain VM_DOMAIN] + [--vm-hostname VM_HOSTNAME] [--vm-username VM_USERNAME] + [--vm-password VM_PASSWORD] [--vm-cleanup] [--json JSON_OUTPUT] + [--xunit XUNIT_OUTPUT] [--journal] + {list,sysinfo,run,multiplex,plugins,datadir} ... + +DESCRIPTION +=========== + +Avocado is an experimental test framework that is built on the experience +accumulated with `autotest` (`http://autotest.github.io`). + +`avocado` is also the name of its test runner command line tool. + +OPTIONS +======= + +The following list of options are builtin `avocado` options. Most other options +are implemented via plugins and will depend on them being loaded. + + -h, --help show a help message and exit + -v, --version show program's version number and exit + -V, --verbose print extra debug messages + --logdir LOGDIR alternate logs directory + --loglevel LOG_LEVEL debug level + --plugins PLUGINS_DIR Load extra plugins from directory + +RUNNING A TEST +============== + +The most common use of the `avocado` command line tool is to run a test:: + + $ avocado run sleeptest + +This command will run the `sleeptest` test, as found on the standard test +directories. The output should be similar to:: + + JOB ID : + JOB LOG : /home//avocado/job-results/job--/job.log + TESTS : 1 + (1/1) sleeptest.py: PASS (1.00 s) + PASS : 1 + ERROR : 0 + FAIL : 0 + SKIP : 0 + WARN : 0 + NOT FOUND : 0 + TIME : 1.00 s + +The test directories will vary depending on you system and +installation method used. Still, it's pretty easy to find that out as shown +in the next section. + +LISTING TESTS +============= + +The `avocado` command line tool also has a `list` command, that lists the +known tests in the standard test directory:: + + $ avocado list + +The output should be similar to:: + + Tests dir: /home//local/avocado/tests + Alias Path + sleeptest /home//local/avocado/tests/sleeptest.py + ... + warntest /home//local/avocado/tests/warntest.py + sleeptenmin /home//local/avocado/tests/sleeptenmin.py + +EXPLORING RESULTS +================= + +When `avocado` runs tests, it saves all its results on your system:: + + JOB ID : + JOB LOG : /home//avocado/job-results/job--/job.log + +For your convenience, `avocado` maintains a link to the latest job run +(an `avocado run` command in this context), so you can always use `"latest"` +to browse your test results:: + + $ ls /home//avocado/job-results/latest + id + job.log + results.json + results.xml + sysinfo + test-results + +The main log file is `job.log`, but every test has its own results directory:: + + $ ls -1 ~/avocado/job-results/latest/test-results/ + sleeptest.py + +Since this is a directory, it should have content similar to:: + + $ ls -1 ~/avocado/job-results/latest/test-results/sleeptest.py/ + data + debug.log + sysinfo + +MULTIPLEX +========= + +Avocado has a powerful tool that enables multiple test scenarios to be run +using a single, unmodified test. This mechanism uses a multiplex file, that +multiplies all possible variations automatically. + +A command by the same name, `multiplex`, is available on the `avocado` +command line tool, and enables you to see all the test scenarios that can +be run:: + + $ avocado multiplex tests/sleeptest.py.data/sleeptest.mplx + Dictionaries generated: + dict 1: sleeptest.short + dict 2: sleeptest.medium + dict 3: sleeptest.long + +For the more curious, you can use the `-c` command line option to see what +parameters would be available to each variation of the sleeptest. + +To run all the test variations you can use:: + + $ avocado run --multiplex tests/sleeptest.py.data/sleeptest.mplx sleeptest + +And the output should look like:: + + ... + (1/3) sleeptest.py.short: PASS (0.50 s) + (2/3) sleeptest.py.medium: PASS (1.00 s) + (3/3) sleeptest.py.long: PASS (5.00 s) + ... + +FILES +===== + +:: + + /etc/avocado/settings.ini + system wide configuration file + +BUGS +==== + +If you find a bug, please report it over our github page as an issue. + +MORE INFORMATION +================ + +For more information check Avocado's online documentation at: `http://avocado-framework.readthedocs.org/` + +Or the project github page at: `http://github.com/avocado-framework` + + +AUTHOR +====== + +Cleber Rosa diff --git a/setup.py b/setup.py index 676187e2..3b713f35 100755 --- a/setup.py +++ b/setup.py @@ -38,12 +38,22 @@ def get_tests_dir(): return settings_system_wide +def get_docs_dir(): + settings_system_wide = os.path.join('/usr', 'share', 'doc', 'avocado') + settings_local_install = '' + if 'VIRTUAL_ENV' in os.environ: + return settings_local_install + else: + return settings_system_wide + + def get_data_files(): data_files = [(get_settings_dir(), ['etc/settings.ini'])] data_files += [(get_tests_dir(), glob.glob('tests/*.py'))] for data_dir in glob.glob('tests/*.data'): fmt_str = '%s/*' % data_dir data_files += [(os.path.join(get_tests_dir(), os.path.basename(data_dir)), [glob.glob(fmt_str)[0]])] + data_files.append((get_docs_dir(), ['man/avocado.rst'])) return data_files -- GitLab