pactest/README

   1 README
   2 ======
   3
   4 pactest is a test suite for the ArchLinux package manager: pacman.
   5
   6 It has a rather high level view of operations performed by pacman: it
   7 automatically creates a test environment based on a test case file
   8 description, the run pacman, and finally check the results of test according
   9 to a set of rules defined in the test case.
  10
  11 It is written in Python and makes available most of what can be found in
  12 pacman's code to create ArchLinux packages or read and write databases entries.
  13
  14 Each test case is defined in a separate file that is sourced in order to set
  15 the environment.
  16
  17 pactest creates the environment in the subdirectory "root" created in the
  18 current directory.
  19 The following directory structure is used:
  20   - var/lib/pacman: databases path (local and sync ones)
  21   - etc/pacman.conf for pacman configuration file
  22   - var/cache/pkg: sync packages cache
  23   - var/log/pactest.log: log file
  24   - var/pub: location for pseudo sync repositories
  25   - tmp: hold all local package archives (to be used with pacman -A or -U)
  26
  27 Note: the logfile is used to capture all pacman outputs.
  28
  29 Test case example:
  30         self.description = "Install a package"
  31
  32         p = pmpkg("dummy", "1.0-3")
  33         p.files = ["bin/dummy",
  34                    "usr/man/man1/dummy.1"]
  35         self.addpkg(p)
  36
  37         self.args = "-A dummy-1.0-1.pkg.tar.gz"
  38
  39         self.addrule("PACMAN_RETCODE=0")
  40         self.addrule("PKG_EXIST=dummy")
  41         for f in p.files:
  42                 self.addrule("FILE_EXIST=%s" % f)
  43
  44 Basically, the above test case will try to install a package (dummy-1.0-3),
  45 including two files, from a local archive, by calling "pacman -A"
  46 Upon completion, it checks that:
  47   - pacman returned no error code,
  48   - a "dummy" entry exists in the "local" database
  49   - all files from the package exist in the filesystem.
  50
  51
  52 Installation
  53 ============
  54
  55 Simply extract the pactest tarball, jump into the newly created directory and
  56 run pactest.py.  See the usage section below.
  57
  58 Remark: pacman 3.x restrictions regarding fakeroot must be disabled.
  59 It can be done by configuring pacman with the --disable-fakeroot flag:
  60         ./configure --disable-fakeroot
  61
  62 For pacman 2.9.x releases, apply the patch found in the patches directory,
  63 then export CFLAGS as following before rebuilding pacman:
  64         export CFLAGS=-DNOFAKEROOT
  65
  66
  67 Usage
  68 =====
  69
  70 pactest will run the suite of tests defined by the "--test" parameter.
  71
  72 Example:
  73         ./pactest.py --test=test/*
  74
  75 This example will run tests from the "test" directory.
  76 Note: several "--test" options can be passed to pactest.
  77
  78 Use the ""help" option to get the full list of parameters:
  79         ./pactest.py --help
  80
  81
  82 Parameters
  83 ==========
  84
  85 The test environment is described by the following basic parameters:
  86
  87         description
  88         -----------
  89
  90 A short string describing the aim of the test case.  It is displayed on the
  91 standard output during test execution.
  92
  93         args
  94         ----
  95
  96 A string of arguments that are passed to the pacman binary when the test is
  97 run.
  98
  99 Example:
 100         self.args = "-S dummy"
 101
 102         option
 103         ------
 104
 105 A dictionary that holds the data used in the pacman configuration file.
 106 It has 3 keys, each one of them pointing at a list of strings:
 107   - noupgrade
 108   - noextract
 109   - ignorepkg
 110
 111 Examples:
 112         self.option["noupgrade"] = ["etc/X11/xorg.conf",
 113                                     "etc/pacman.conf"]
 114         self.option["noextract"] = ["etc/lilo.conf"]
 115
 116         filesystem
 117         ----------
 118
 119 A list of strings describing a set of files supposed to exist in the filesystem
 120 when the test case is run.
 121 Upon test startup, pactest will automatically populate the test environment
 122 filesystem with this list of files.
 123
 124 Example:
 125         self.filesystem = ["bin/dummy",
 126                            "etc/X11/xorg.conf.pacsave"]
 127
 128 Note that all paths are relative ones, and thus file names should not start
 129 with a "/".
 130
 131
 132 Packages
 133 ========
 134
 135 The test case file description shall define a number of packages that can be
 136 used to either populate a database, or to feed pacman with data needed during
 137 its execution.
 138
 139 This can be achieved by creating pmpkg objects, with the following constructor:
 140   pmpkg(name, version)
 141
 142 Both "name" and "version" are strings.  Also, note that if not provided, the
 143 version defaults to "1.0-1".
 144
 145 Example:
 146         pkg1 = pmpkg("dummy", "2.1-1")
 147         pkg2 = pmpkg("foobar")
 148
 149 All fields from a ArchLinux package can be set and modified directly with no
 150 methods to access them.
 151 Note: some fields are automatically set by pactest and should preferably not
 152 be modified by hand (i.e. "md5sum", "size", or "csize").
 153
 154 Examples:
 155         pkg.depends = ["pkg2", "pkg3>=2.0"]
 156         pkg.files = ["bin/dummy", "etc/dummy.conf", "usr/man/man1/dummy.1"]
 157
 158
 159 Databases
 160 =========
 161
 162 The test environment provides a way to create and fill databases (local or
 163 sync ones).
 164
 165 The following methods shall be used:
 166
 167         * addpkg2db(database, package)
 168
 169 Notes: "database" is a string, and "package" shall be a previously created
 170 pmpkg object.
 171
 172 Examples:
 173         self.addpkg2db("local", lpkg)
 174         self.addpkg2db("sync1", spkg11)
 175         self.addpkg2db("sync1", spkg12)
 176         self.addpkg2db("sync2", spkg21)
 177
 178 Note: there is no need to explicitly create a database.  The "local" one
 179 already exists (even if empty), and sync databases are created on the fly when
 180 a new database new is given.
 181
 182         * addpkg(package)
 183
 184 package is an existing pmpkg object.
 185 It creates a package archive based on the given object.  The resulting archive
 186 is located in the temporary directory of the test environment, ready to be
 187 supplied to pacman for test purposes.
 188
 189
 190 Files
 191 =====
 192
 193 All files created by pactest are filled with a content defaulting to the file
 194 name, with an additional line feed.
 195 For instance, the content of a file "bin/dummy" created in the test environment
 196 file system is: "bin/dummy\n".
 197
 198 It is possible to create directories by appending a slash "/" to the name and
 199 to create symlinks by appending an arrow followed by a filename " -> target".
 200
 201 Note: only relative symlinks are supported.
 202
 203 Example:
 204         pkg = pmpkg("dummy")
 205         pkg.files = ["bin/dummy",
 206                      "usr/local/",
 207                      "lib/libfoo.so.O",
 208                      "lib/libfoo.so -> ./libfoo.so.0"]
 209
 210 In this example, "usr/local/" is a directory, and "libfoo.so" will be a
 211 symlink pointing at "libfoo.so.0".  It is usually a good idea to also define
 212 the target of the symlink!
 213
 214 It can be interesting for some tests to create altered files.  This can be
 215 done by appending one or more asterisks "*" to the file name.
 216
 217 Example:
 218         lpkg = pmpkg("dummy")
 219         lpkg.files = ["bin/dummy"]
 220         self.addpkg2db("local", lpkg)
 221
 222         newpkg = pmpkg("dummy", "1.0-2")
 223         newpkg.files = ["bin/dummy*"]
 224         self.addpkg(newpkg)
 225
 226         self.args = "-U dummy-1.0-2.pkg.tar.gz"
 227
 228 In this case, package "lpkg" will install a file "bin/dummy" with "bin/dummy\n"
 229 as its content.  Upon package upgrade, newpkg will provide a file named
 230 "bin/dummy" with "bin/dummy*\n" as its content.
 231 This is useful to simulate that a file has been modified between two different
 232 releases of a same package.
 233
 234 The same also applies to files from  the "filesystem" parameter of the test
 235 environment, and to the "backup" attribute of a package object.
 236
 237
 238 Rules
 239 =====
 240
 241 Finally, to check test success or failure, one shall define a set of rules.
 242
 243         addrule(rule)
 244         -------------
 245
 246 A rule is a string composed by a key and an item, joined with a "=" symbol.
 247
 248 Examples:
 249         self.addrule("PACMAN_RETCODE=0")
 250         self.addrule("PKG_EXIST=dummy")
 251         self.addrule("FILE_MODIFIED=bin/dummy")
 252         self.addrule("PKG_DEPENDS=xorg|fontconfig")
 253
 254 Note: an item can be divided into two arguments, as shown in the latter
 255 example.
 256
 257 All rules can be prepended with a bang "!" in order to tell pactest to expect
 258 the exact opposite result.
 259
 260 Example:
 261         self.addrule("!FILE_MODIFIED=bin/dummy")
 262
 263 Finally, the following rules are supported:
 264
 265         . PACMAN rules
 266
 267 Possible rules are:
 268
 269   PACMAN_RETCODE=value
 270   PACMAN_OUTPUT=value
 271
 272 For RETCODE, pactest will ensure the pacman return code is the value given.
 273 For OUTPUT, pactest will grep pacman outputs for the given value.
 274
 275 Note: PACMAN_OUTPUT should not be used. Pacman outputs are likely to change
 276 from one release to another, so that it's reliability is quite low.
 277
 278         . PKG rules
 279
 280 For each rule, pactest will read the entry "name" from the local database and
 281 challenge the requested data with it.
 282
 283 Possible rules are:
 284
 285   PKG_EXIST=name
 286   PKG_MODIFIED=name
 287   PKG_VERSION=name|version
 288   PKG_GROUPS=name|group
 289   PKG_PROVIDES=name|providename
 290   PKG_DEPENDS=name|depname
 291   PKG_OPTDEPENDS=name|depname
 292   PKG_REASON=name|intvalue
 293   PKG_FILES=name|filename
 294   PKG_BACKUP=name|backupname
 295
 296 Example:
 297         PKG_DEPENDS=ncurses|glibc
 298
 299 pactest will test to ensure the local database entry "ncurses" has "glibc" in
 300 its DEPENDS field.
 301
 302         . FILE rules
 303
 304   FILE_EXIST=path/to/file
 305   FILE_MODIFIED=path/to/file
 306   FILE_MODE=path/to/file|octal
 307   FILE_TYPE=path/to/file|type  (possible types: dir, file, link)
 308   FILE_PACNEW=path/to/file
 309   FILE_PACSAVE=path/to/file
 310   FILE_PACORIG=path/to/file
 311
 312 Example:
 313         FILE_EXIST=etc/test.conf
 314
 315 pactest will ensure the file /etc/test.conf exists in the filesystem.
 316