Move pacman test suite

Move the test suite to test/pacman in order to make a logical
location for a future makepkg test suite.

Signed-off-by: Allan McRae <allan@archlinux.org>
Signed-off-by: Dan McGee <dan@archlinux.org>

1 files changed, 323 insertions, 0 deletions

diff --git a/test/pacman/README b/test/pacman/README
new file mode 100644
index 00000000..8f97a17d
--- /dev/null
+++ b/test/pacman/README
@@ -0,0 +1,323 @@
+README
+======
+
+pactest is a test suite for the ArchLinux package manager: pacman.
+
+It has a rather high level view of operations performed by pacman: it
+automatically creates a test environment based on a test case file 
+description, the run pacman, and finally check the results of test according 
+to a set of rules defined in the test case.
+
+It is written in Python and makes available most of what can be found in 
+pacman's code to create ArchLinux packages or read and write databases entries.
+
+Each test case is defined in a separate file that is sourced in order to set 
+the environment.
+
+pactest creates the environment in the subdirectory "root" created in the 
+current directory.
+The following directory structure is used:
+  - var/lib/pacman: databases path (local and sync ones)
+  - etc/pacman.conf for pacman configuration file
+  - var/cache/pkg: sync packages cache
+  - var/log/pactest.log: log file
+  - var/pub: location for pseudo sync repositories
+  - tmp: hold all local package archives (to be used with pacman -A or -U)
+ 
+Note: the logfile is used to capture all pacman outputs.
+
+Test case example:
+	self.description = "Install a package"
+
+	p = pmpkg("dummy", "1.0-3")
+	p.files = ["bin/dummy",
+	           "usr/man/man1/dummy.1"]
+	self.addpkg(p)
+
+	self.args = "-A dummy-1.0-1.pkg.tar.gz"
+
+	self.addrule("PACMAN_RETCODE=0")
+	self.addrule("PKG_EXIST=dummy")
+	for f in p.files:
+		self.addrule("FILE_EXIST=%s" % f)
+
+Basically, the above test case will try to install a package (dummy-1.0-3), 
+including two files, from a local archive, by calling "pacman -A"
+Upon completion, it checks that:
+  - pacman returned no error code,
+  - a "dummy" entry exists in the "local" database
+  - all files from the package exist in the filesystem.
+
+
+Installation
+============
+
+Simply extract the pactest tarball, jump into the newly created directory and 
+run pactest.py.  See the usage section below.
+
+Remark: pacman 3.x restrictions regarding fakeroot must be disabled.
+It can be done by configuring pacman with the --disable-fakeroot flag:
+	./configure --disable-fakeroot
+
+For pacman 2.9.x releases, apply the patch found in the patches directory, 
+then export CFLAGS as following before rebuilding pacman:
+	export CFLAGS=-DNOFAKEROOT
+
+
+Usage
+=====
+
+pactest will run the suite of tests defined by the "--test" parameter.
+
+Example:
+	./pactest.py --test tests/*.py
+
+This example will run all tests from the "tests" directory.
+Note: several "--test" options can be passed to pactest.
+
+Use the "help" option to get the full list of parameters:
+	./pactest.py --help
+
+
+Parameters
+==========
+
+The test environment is described by the following basic parameters:
+
+	description
+	-----------
+
+A short string describing the aim of the test case.  It is displayed on the 
+standard output during test execution.
+
+	args
+	----
+
+A string of arguments that are passed to the pacman binary when the test is 
+run.
+
+Example:
+	self.args = "-S dummy"
+
+	option
+	------
+
+A dictionary that holds the data used in the pacman configuration file.
+The following options are known to be useful in pactest tests; this list
+is not necessarily complete:
+  - HoldPkg
+  - IgnorePkg
+  - IgnoreGroup
+  - SyncFirst
+  - NoExtract
+  - NoUpgrade
+  - XferCommand
+
+For documentation on these options, see the pacman.conf documentation.
+
+Examples:
+	self.option["NoUpgrade"] = ["etc/X11/xorg.conf",
+	                            "etc/pacman.conf"]
+	self.option["NoExtract"] = ["etc/lilo.conf"]
+
+	filesystem
+	----------
+
+A list of strings describing a set of files supposed to exist in the filesystem 
+when the test case is run.
+Upon test startup, pactest will automatically populate the test environment 
+filesystem with this list of files.
+
+Example:
+	self.filesystem = ["bin/dummy",
+	                   "etc/X11/xorg.conf.pacsave"]
+
+Note that all paths are relative ones, and thus file names should not start 
+with a "/".
+
+
+Packages
+========
+
+The test case file description shall define a number of packages that can be 
+used to either populate a database, or to feed pacman with data needed during 
+its execution.
+
+This can be achieved by creating pmpkg objects, with the following constructor:
+  pmpkg(name, version)
+
+Both "name" and "version" are strings.  Also, note that if not provided, the 
+version defaults to "1.0-1".
+
+Example:
+	pkg1 = pmpkg("dummy", "2.1-1")
+	pkg2 = pmpkg("foobar")
+
+All fields from a ArchLinux package can be set and modified directly with no 
+methods to access them.
+Note: some fields are automatically set by pactest and should preferably not 
+be modified by hand (i.e. "md5sum", "size", or "csize").
+
+Examples:
+	pkg.depends = ["pkg2", "pkg3>=2.0"]
+	pkg.files = ["bin/dummy", "etc/dummy.conf", "usr/man/man1/dummy.1"]
+
+
+Databases
+=========
+
+The test environment provides a way to create and fill databases (local or 
+sync ones).
+
+The following methods shall be used:
+
+	* addpkg2db(database, package)
+
+Notes: "database" is a string, and "package" shall be a previously created 
+pmpkg object.
+
+Examples:
+	self.addpkg2db("local", lpkg)
+	self.addpkg2db("sync1", spkg11)
+	self.addpkg2db("sync1", spkg12)
+	self.addpkg2db("sync2", spkg21)
+
+Note: there is no need to explicitly create a database.  The "local" one 
+already exists (even if empty), and sync databases are created on the fly when 
+a new database new is given.
+
+	* addpkg(package)
+
+package is an existing pmpkg object.
+It creates a package archive based on the given object.  The resulting archive 
+is located in the temporary directory of the test environment, ready to be 
+supplied to pacman for test purposes.
+
+
+Files
+=====
+
+All files created by pactest are filled with a content defaulting to the file
+name, with an additional line feed.
+For instance, the content of a file "bin/dummy" created in the test environment
+file system is: "bin/dummy\n".
+
+It is possible to create directories by appending a slash "/" to the name and 
+to create symlinks by appending an arrow followed by a filename " -> target".
+
+Note: only relative symlinks are supported.
+
+Example:
+	pkg = pmpkg("dummy")
+	pkg.files = ["bin/dummy",
+	             "usr/local/",
+	             "lib/libfoo.so.O",
+	             "lib/libfoo.so -> ./libfoo.so.0"]
+
+In this example, "usr/local/" is a directory, and "libfoo.so" will be a 
+symlink pointing at "libfoo.so.0".  It is usually a good idea to also define 
+the target of the symlink!
+
+It can be interesting for some tests to create altered files.  This can be 
+done by appending one or more asterisks "*" to the file name.
+
+Example:
+	lpkg = pmpkg("dummy")
+	lpkg.files = ["bin/dummy"]
+	self.addpkg2db("local", lpkg)
+
+	newpkg = pmpkg("dummy", "1.0-2")
+	newpkg.files = ["bin/dummy*"]
+	self.addpkg(newpkg)
+
+	self.args = "-U dummy-1.0-2.pkg.tar.gz"
+
+In this case, package "lpkg" will install a file "bin/dummy" with "bin/dummy\n" 
+as its content.  Upon package upgrade, newpkg will provide a file named 
+"bin/dummy" with "bin/dummy*\n" as its content.
+This is useful to simulate that a file has been modified between two different 
+releases of a same package.
+
+The same also applies to files from  the "filesystem" parameter of the test 
+environment, and to the "backup" attribute of a package object.
+
+
+Rules
+=====
+
+Finally, to check test success or failure, one shall define a set of rules.
+
+	addrule(rule)
+	-------------
+
+A rule is a string composed by a key and an item, joined with a "=" symbol.
+
+Examples:
+	self.addrule("PACMAN_RETCODE=0")
+	self.addrule("PKG_EXIST=dummy")
+	self.addrule("FILE_MODIFIED=bin/dummy")
+	self.addrule("PKG_DEPENDS=xorg|fontconfig")
+
+Note: an item can be divided into two arguments, as shown in the latter 
+example.
+
+All rules can be prepended with a bang "!" in order to tell pactest to expect 
+the exact opposite result.
+
+Example:
+	self.addrule("!FILE_MODIFIED=bin/dummy")
+
+Finally, the following rules are supported:
+
+	. PACMAN rules
+
+Possible rules are:
+
+  PACMAN_RETCODE=value
+  PACMAN_OUTPUT=value
+
+For RETCODE, pactest will ensure the pacman return code is the value given.
+For OUTPUT, pactest will grep pacman outputs for the given value.
+
+Note: PACMAN_OUTPUT should not be used. Pacman outputs are likely to change 
+from one release to another, so that it's reliability is quite low.
+
+	. PKG rules
+
+For each rule, pactest will read the entry "name" from the local database and 
+challenge the requested data with it.
+
+Possible rules are:
+
+  PKG_EXIST=name
+  PKG_MODIFIED=name
+  PKG_VERSION=name|version
+  PKG_GROUPS=name|group
+  PKG_PROVIDES=name|providename
+  PKG_DEPENDS=name|depname
+  PKG_OPTDEPENDS=name|depname
+  PKG_REASON=name|intvalue
+  PKG_FILES=name|filename
+  PKG_BACKUP=name|backupname
+
+Example:
+	PKG_DEPENDS=ncurses|glibc
+
+pactest will test to ensure the local database entry "ncurses" has "glibc" in
+its DEPENDS field.
+
+	. FILE rules
+
+  FILE_EXIST=path/to/file
+  FILE_MODIFIED=path/to/file
+  FILE_MODE=path/to/file|octal
+  FILE_TYPE=path/to/file|type  (possible types: dir, file, link)
+  FILE_PACNEW=path/to/file
+  FILE_PACSAVE=path/to/file
+  FILE_PACORIG=path/to/file
+
+Example:
+	FILE_EXIST=etc/test.conf
+
+pactest will ensure the file /etc/test.conf exists in the filesystem.
+