On 08/28/2013 12:02 AM, Rob Crittenden wrote:
Petr Viktorin wrote:
Hello,
This patch adds man pages for testing tools.
As far as I can see, we use autotools for installing man pages. I added
the autotools machinery to ipatests/man only. I'd appreciate if an
autotools expert could check if this approach is OK.
Or would it be better to not use autotools at all here?
https://fedorahosted.org/freeipa/ticket/3855 (part 5)
Thanks for the review!
You don't have any man pages in section 8 so that can be removed from
Makefile.am.
Removed
You need to add a line break for the various ways to run the commands.
ipa-test-config [options]
ipa-test-config [options] --global
ipa-test-config [options] hostname
renders as
ipa-test-config [options] ipa-test-config [options] --global
ipa-test-config [options] hostname
Added
ipa-test-config lacks a header.
Which header do you mean? I see the same header as on the other pages.
ipa-test-config doesn't say where the configuration is stored.
It is not stored anywhere; it's read from environment variables and
printed to stdout. I've clarified the description a bit.
ipa-test-task, in the install-topo description drop the word Please.
Removed
Almost none of the 72 options to ipa-run-test are documented in the man
page.
These are taken from the "nosetests" command and documented in
nosetests(1). Also, the list can change depending on what plugins are
installed.
I think pointing the reader to nosetests(1) is enough.
rob
It's a shame the test commands don't run in the tree.
Well, they will work in-tree if you set PYTHONPATH to the tree.
For example these work without the packages installed:
PYTHONPATH=. ./ipatests/ipa-run-tests test_ipalib/test_config.py
PYTHONPATH=. ./ipatests/ipa-test-task uninstall-all
You can also point the system-installed ipa-run-tests to in-tree tests.
You just need to use an absolute path because it changes the current
directory:
ipa-run-tests `pwd`/ipatests/test_ipalib/test_config.py
--
Petr³
From 272d740a7c8514eee5e5cc50036b1b3de77e4775 Mon Sep 17 00:00:00 2001
From: Petr Viktorin <pvikt...@redhat.com>
Date: Tue, 13 Aug 2013 18:32:36 +0200
Subject: [PATCH] Add man pages for testing tools
Add man pages for ipa-run-tests, ipa-test-task, and ipa-test-config.
https://fedorahosted.org/freeipa/ticket/3855 (part 5)
---
.gitignore | 5 ++
Makefile | 7 +-
freeipa.spec.in | 6 ++
ipatests/man/Makefile.am | 18 +++++
ipatests/man/configure.ac | 24 +++++++
ipatests/man/ipa-run-tests.1 | 63 +++++++++++++++++
ipatests/man/ipa-test-config.1 | 157 +++++++++++++++++++++++++++++++++++++++++
ipatests/man/ipa-test-task.1 | 126 +++++++++++++++++++++++++++++++++
8 files changed, 405 insertions(+), 1 deletion(-)
create mode 100644 ipatests/man/Makefile.am
create mode 100644 ipatests/man/configure.ac
create mode 100644 ipatests/man/ipa-run-tests.1
create mode 100644 ipatests/man/ipa-test-config.1
create mode 100644 ipatests/man/ipa-test-task.1
diff --git a/.gitignore b/.gitignore
index 738b00b13b7014ea915da9bcd06ab1ac4eee3764..5252dad1befa9279b8e5cd033e395309f6a9ae8a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -81,6 +81,11 @@ ipa-client/py-compile
ipa-client/stamp-h1
ipa-client/version.m4
ipatests/test_xmlrpc/service.crt
+ipatests/man/aclocal.m4
+ipatests/man/autom4te.cache/
+ipatests/man/config.status
+ipatests/man/install-sh
+ipatests/man/missing
freeipa.spec
ipapython/setup.py
ipapython/version.py
diff --git a/Makefile b/Makefile
index 674143b8df14e93833d87fcea5740efbb28a9374..a21cf7e33275fd1a783e89baf237c8dcd8db6508 100644
--- a/Makefile
+++ b/Makefile
@@ -71,6 +71,9 @@ client-autogen: version-update
cd ipa-client; if [ ! -e Makefile ]; then ../autogen.sh --prefix=/usr --sysconfdir=/etc --localstatedir=/var --libdir=$(LIBDIR); fi
cd install; if [ ! -e Makefile ]; then ../autogen.sh --prefix=/usr --sysconfdir=/etc --localstatedir=/var --libdir=$(LIBDIR); fi
+tests-man-autogen: version-update
+ cd ipatests/man; if [ ! -e Makefile ]; then ../../autogen.sh --prefix=/usr --sysconfdir=/etc --localstatedir=/var --libdir=$(LIBDIR); fi
+
install: all server-install tests-install
@for subdir in $(SUBDIRS); do \
(cd $$subdir && $(MAKE) $@) || exit 1; \
@@ -153,15 +156,17 @@ server-install: server
$(PYTHON) setup.py install --root $(DESTDIR); \
fi
-tests: version-update
+tests: version-update tests-man-autogen
cd ipatests; $(PYTHON) setup.py build
+ cd ipatests/man && $(MAKE) all
tests-install: tests
if [ "$(DESTDIR)" = "" ]; then \
cd ipatests; $(PYTHON) setup.py install; \
else \
cd ipatests; $(PYTHON) setup.py install --root $(DESTDIR); \
fi
+ cd ipatests/man && $(MAKE) install
archive:
-mkdir -p dist
diff --git a/freeipa.spec.in b/freeipa.spec.in
index 46a2ae0210c6b75fea971f5d02a10db22815787c..67bd3667db42ebb3639f50a4dd0c3a9fda000781 100644
--- a/freeipa.spec.in
+++ b/freeipa.spec.in
@@ -830,9 +830,15 @@ fi
%{_bindir}/ipa-test-config
%{_bindir}/ipa-test-task
%{python_sitelib}/ipatests-*.egg-info
+%{_mandir}/man1/ipa-run-tests.1.gz
+%{_mandir}/man1/ipa-test-config.1.gz
+%{_mandir}/man1/ipa-test-task.1.gz
%endif # ONLY_CLIENT
%changelog
+* Wed Aug 14 2013 Petr Viktorin <pvikt...@redhat.com> - 3.3.90-2
+- Add man pages to the tests subpackage
+
* Mon Aug 12 2013 Petr Viktorin <pvikt...@redhat.com> - 3.3.90-1
- Downgrade required version of python-paramiko for the tests subpackage
diff --git a/ipatests/man/Makefile.am b/ipatests/man/Makefile.am
new file mode 100644
index 0000000000000000000000000000000000000000..fcd3d1d3682cd4d62c5f0ff1d2d2ef1d8538ddc9
--- /dev/null
+++ b/ipatests/man/Makefile.am
@@ -0,0 +1,18 @@
+# This file will be processed with automake-1.7 to create Makefile.in
+
+AUTOMAKE_OPTIONS = 1.7
+
+NULL=
+
+man1_MANS = \
+ ipa-run-tests.1 \
+ ipa-test-config.1 \
+ ipa-test-task.1 \
+ $(NULL)
+
+install-data-hook:
+ @for i in $(man1_MANS) ; do gzip -f $(DESTDIR)$(man1dir)/$$i ; done
+
+MAINTAINERCLEANFILES = \
+ Makefile.in \
+ $(NULL)
diff --git a/ipatests/man/configure.ac b/ipatests/man/configure.ac
new file mode 100644
index 0000000000000000000000000000000000000000..8ddb93abb564c81767ff8cd4f482b896e655fc43
--- /dev/null
+++ b/ipatests/man/configure.ac
@@ -0,0 +1,24 @@
+AC_PREREQ(2.59)
+m4_include(../../version.m4)
+AC_INIT([ipa-tests],
+ IPA_VERSION,
+ [https://hosted.fedoraproject.org/projects/freeipa/newticket])
+
+AM_INIT_AUTOMAKE([foreign])
+
+AM_MAINTAINER_MODE
+
+AC_SUBST(VERSION)
+AC_SUBST([INSTALL_DATA], ['$(INSTALL) -m 644 -p'])
+
+AC_PROG_MKDIR_P
+AC_PROG_AWK
+AC_PROG_SED
+
+# Files
+
+AC_CONFIG_FILES([
+ Makefile
+])
+
+AC_OUTPUT
diff --git a/ipatests/man/ipa-run-tests.1 b/ipatests/man/ipa-run-tests.1
new file mode 100644
index 0000000000000000000000000000000000000000..a877f7ac73fd420e79b9778998ae3864a3b309dc
--- /dev/null
+++ b/ipatests/man/ipa-run-tests.1
@@ -0,0 +1,63 @@
+.\" A man page for ipa-run-tests
+.\" Copyright (C) 2013 Red Hat, Inc.
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+.\" General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
+.\"
+.\" Author: Petr Viktorin <pvikt...@redhat.com>
+.\"
+.TH "ipa-run-tests" "1" "Sep 12 2013" "FreeIPA" "FreeIPA Manual Pages"
+.SH "NAME"
+ipa\-run\-tests \- Run the FreeIPA test suite
+.SH "SYNOPSIS"
+ipa\-run\-tests [options]
+.SH "DESCRIPTION"
+ipa\-run\-tests is a wrapper around nosetests that run the FreeIPA test suite.
+It is intended to be used for developer testing and in continuous
+integration systems.
+
+It loads IPA-internal Nose plugins ordered-tests and beakerlib.
+The ordered-tests plugin is enabled automatically.
+
+The FreeIPA test suite installed system\-wide is selected via Nose's \-\-where
+option.
+It is possible to select a subset of the entire test suite by specifying
+a test file relative to the ipatests package, for example:
+
+ ipa-run-tests test_integration/test_simple_replication.py
+
+.SH "OPTIONS"
+All command-line options are passed to the underlying Nose runner.
+See nosetests(1) for a complete list.
+
+The internal IPA plugins add an extra option:
+
+.TP
+\fB\-\-with-beakerlib\fR
+Enable BeakerLib integration.
+Test phases, failures and passes, and log messages are reported using
+beakerlib(1) commands.
+This option requires the beakerlib.sh script to be sourced.
+
+.SH "EXIT STATUS"
+0 if the command was successful
+
+nonzero if any error or failure occurred
+
+.SH "CONFIGURATION"
+Please see ipa-test-config(1) for a description of configuration environment
+variables.
+
+.SH "REFERENCES"
+A full description of the FreeIPA integration testing framework is available at
+http://www.freeipa.org/page/V3/Integration_testing
diff --git a/ipatests/man/ipa-test-config.1 b/ipatests/man/ipa-test-config.1
new file mode 100644
index 0000000000000000000000000000000000000000..64b78b44e45a060ea129562a4ec58ed15ba7deb4
--- /dev/null
+++ b/ipatests/man/ipa-test-config.1
@@ -0,0 +1,157 @@
+.\" A man page for ipa-test-config
+.\" Copyright (C) 2013 Red Hat, Inc.
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+.\" General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
+.\"
+.\" Author: Petr Viktorin <pvikt...@redhat.com>
+.\"
+.TH "ipa-test-config" "1" "Sep 12 2013" "FreeIPA" "FreeIPA Manual Pages"
+.SH "NAME"
+ipa\-test\-config \- Generate FreeIPA test configuration for use in Bash scripts
+.SH "SYNOPSIS"
+ipa\-test\-config [options]
+.br
+ipa\-test\-config [options] --global
+.br
+ipa\-test\-config [options] hostname
+.SH "DESCRIPTION"
+The FreeIPA integration test suite is configured by setting environment
+variables.
+The ipa\-run\-tests command reads these variables and prints detailed
+configuration for shell-based scripts to standard output.
+The output of ipa\-run\-tests consists of export statements that can be
+sourced by Bash.
+
+If run without arguments, it prints out configuration specific to the local
+host.
+Another host may be specified as an argument, or via the \-\-master,
+\-\-replica, and \-\-client options.
+With the --global option, it prints only configuration that is not specific to
+any host.
+
+.SH "OPTIONS"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print out the command's usage and exit
+.TP
+\fB\-\-global\fR
+Output global configuration.
+.TP
+\fB\-\-domain\fR
+Output configuration for the given domain (environment).
+May be given as an index or name.
+By default, domain 1 is used.
+.TP
+\fB\-\-master\fR
+Output configuration for the master
+.TP
+\fB\-\-replica\fR
+Output configuration for the replica with the given number
+.TP
+\fB\-\-replica\fR
+Output configuration for the client with the given number
+.TP
+\fB\-\-no\-simple\fR
+Do not output Simple Vars.
+These are normally included for backwards compatibility.
+
+.SH "ENVIRONMENT VARIABLES"
+
+.TP
+Host configuration:
+
+.TP
+\fB$MASTER\fR
+ FQDN of the first IPA server
+.TP
+\fB$REPLICA\fR
+ FQDNs of other IPA servers (space-separated)
+.TP
+\fB$CLIENT\fR
+ FQDNs of IPA clients (space-separated)
+.TP
+\fB$MASTER_env2\fR, \fB$REPLICA_env2\fR, \fB$CLIENT_env2\fR, \fB$MASTER_env3\fR, ...
+ can be used for additional domains when needed
+.TP
+\fB$BEAKER\fR<role><num>\fB_IP_env\fR<e>, e.g. \fB$BEAKERREPLICA1_IP_env1\fR
+ the IP address of the given host
+ Default: resolved via gethostbyname (or DNS if $IPv6SETUP is set)
+
+.TP
+Basic configuration:
+
+.TP
+\fB$IPATEST_DIR\fR
+ Directory for test data on the remote hosts
+ Default: /root/ipatests
+.TP
+\fB$DNSFORWARD\fR
+ IP of a DNS forwarder
+ Default: 8.8.8.8
+.TP
+\fB$IPA_ROOT_SSH_PASSWORD\fR
+ root password for the remote machines
+ Used if $IPA_ROOT_SSH_KEY is not set.
+.TP
+\fB$IPA_ROOT_SSH_KEY\fR
+ name of a file containing the private RSA key for root on the remote machines
+ Default: ~/.ssh/id_rsa
+
+.TP
+Test customization:
+
+.TP
+\fB$DOMAIN\fR
+ IPA domain name
+ Default: taken from $MASTER
+.TP
+\fB$NISDOMAIN\fR
+ NIS domain name
+ Default: ipatest
+.TP
+\fB$NTPSERVER\fR
+ NIS domain name
+ Default: ipatest
+.TP
+\fB$IPv6SETUP\fR
+ Set to TRUE for IPv6-only connectivity
+.TP
+\fB$IPADEBUG\fR
+ Set to enable test debugging
+
+.TP
+\fB$ADMINID\fR
+ Admin username
+ Default: admin
+.TP
+\fB$ADMINPW\fR
+ Admin user password
+ Default: Secret123
+.TP
+\fB$ROOTDN\fR
+ Directory manager DN
+ Default: cn=Directory Manager
+.TP
+\fB$ROOTDNPWD\fR
+ Directory manager password
+ Default: Secret123
+
+.SH "EXIT STATUS"
+0 if the command was successful
+
+1 if an error occurred
+
+.SH "REFERENCES"
+A full description of the FreeIPA integration testing framework is available at
+http://www.freeipa.org/page/V3/Integration_testing
diff --git a/ipatests/man/ipa-test-task.1 b/ipatests/man/ipa-test-task.1
new file mode 100644
index 0000000000000000000000000000000000000000..61b0cda9570bc5c612e2a364512f364d0ebe9239
--- /dev/null
+++ b/ipatests/man/ipa-test-task.1
@@ -0,0 +1,126 @@
+.\" A man page for ipa-test-task
+.\" Copyright (C) 2013 Red Hat, Inc.
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+.\" General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
+.\"
+.\" Author: Petr Viktorin <pvikt...@redhat.com>
+.\"
+.TH "ipa-test-task" "1" "Sep 12 2013" "FreeIPA" "FreeIPA Manual Pages"
+.SH "NAME"
+ipa\-test\-task \- Run a task for FreeIPA testing
+.SH "SYNOPSIS"
+ipa\-test\-task -h
+.br
+ipa\-test\-task [global-options] TASK [task-options]
+.SH "DESCRIPTION"
+Run a task using FreeIPA integration testing configuration.
+This tool is meant for use in scripts that test FreeIPA functionality.
+See ipa-test-config(1) for FreeIPA integration test configuration.
+
+This tool should never be run in a production environment.
+It is not designed with security in mind.
+
+.SH "GLOBAL OPTIONS"
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print out the command's usage and exit.
+If given after a subcommand, prints that subcommand's usage message.
+
+.TP
+\fB\-\-with\-beakerlib\fR
+Enable BeakerLib integration.
+Log messages are reported via beakerlib(1) commands.
+This option requires an active BeakerLib phase.
+
+.SH "SUBCOMMANDS"
+.TP
+\fBipa\-test\-task install\-master [\-\-host HOST]\fR
+Install an initial IPA server on the given host, or on the configured master
+if \-\-host is not given.
+
+.TP
+\fBipa\-test\-task install\-replica [\-\-master MASTER] HOST\fR
+Install an IPA replica on the given host.
+It is initialized from the IPA server given by \-\-master, or from the
+configured master if \-\-master is not given.
+
+.TP
+\fBipa\-test\-task install\-client [\-\-master MASTER] HOST\fR
+Install an IPA client on the given host.
+It is initialized from the IPA server given by \-\-master, or from the
+configured master if \-\-master is not given.
+
+.TP
+\fBipa\-test\-task connect\-replica HOST1 HOST2\fR
+Create a replication agreement between two given replicas.
+
+.TP
+\fBipa\-test\-task disconnect\-replica HOST1 HOST2\fR
+Remove a replication agreement between two given replicas.
+
+.TP
+\fBipa\-test\-task uninstall\-server [HOST [HOST ...]]\fR
+Uninstall an IPA server (master or replica) on the given host(s), and
+restore the host(s) to the state before installation.
+If no host is given, uninstalls all configured masters and replicas.
+If no server is installed on a host, does nothing on that host.
+
+.TP
+\fBipa\-test\-task uninstall\-client [HOST [HOST ...]]\fR
+Uninstall an IPA client on the given host(s), and restore the host(s) to the
+state before installation.
+If no host is given, uninstalls all configured clients.
+If no client is installed on a host, does nothing on that host.
+
+.TP
+\fBipa\-test\-task uninstall\-all\fR
+Uninstall IPA from all configured master, replica and client hosts.
+Equivalent to running uninstall\-server and uninstall\-client without
+arguments.
+
+.TP
+\fBipa\-test\-task cleanup [HOST [HOST ...]]\fR
+Restore system configuration (such as /etc/resolv.conf) on the given hosts
+to a state before installation.
+If no hosts are given, clean up all configured hosts.
+This functionality is included in the uninstall\-* subcommands and is rarely
+useful alone.
+
+.TP
+\fBipa\-test\-task install-topo [\-\-skip\-master] [\-\-skip\-clients] [\-\-master M] [\-\-replicas R1 [R2...]] [\-\-clients C1 [C2 ...]] TOPO\fR
+Install a number of FreeIPA servers and clients in the given topology.
+Use the list\-topos subcommand for a list of available topologies.
+
+Unless \-\-skip\-master is given, an initial server is installed on the host
+given by \-\-master, or on the configured master if \-\-master is missing.
+
+Replicas are installed according to the selected topology on hosts given by
+\-\-replicas, or on all configured replicas if that option is not given.
+
+Unless \-\-skip\-clients is given, clients are installed on hosts given by
+\-\-clients, or on all configured clients if \-\-clients is not given.
+Servers used for client installation are selected in a round-robin fashion.
+
+.TP
+\fBipa\-test\-task list-topos\fR
+List the topologies available for the install-topo subcommand.
+
+.SH "EXIT STATUS"
+0 if the command was successful
+
+nonzero if an error occurred
+
+.SH "REFERENCES"
+A full description of the FreeIPA integration testing framework is available at
+http://www.freeipa.org/page/V3/Integration_testing
--
1.8.3.1
_______________________________________________
Freeipa-devel mailing list
Freeipa-devel@redhat.com
https://www.redhat.com/mailman/listinfo/freeipa-devel
