summaryrefslogtreecommitdiff
path: root/pactest/README
diff options
context:
space:
mode:
authorAllan McRae <allan@archlinux.org>2010-05-30 14:41:59 +1000
committerDan McGee <dan@archlinux.org>2010-06-02 13:14:51 -0500
commit844d82fad811626b0b8e54db60ee4b3ea32a3cb9 (patch)
treed6ae52c513db060b1f81227c34bfb366ea3fa58c /pactest/README
parentccea1b55766200c1ab371cf0f3b38c4cebdb2063 (diff)
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>
Diffstat (limited to 'pactest/README')
-rw-r--r--pactest/README323
1 files changed, 0 insertions, 323 deletions
diff --git a/pactest/README b/pactest/README
deleted file mode 100644
index 8f97a17d..00000000
--- a/pactest/README
+++ /dev/null
@@ -1,323 +0,0 @@
-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.
-