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 tests/*.py
  74
  75 This example will run all tests from the "tests" 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 The following options are known to be useful in pactest tests; this list
 107 is not necessarily complete:
 108   - HoldPkg
 109   - IgnorePkg
 110   - IgnoreGroup
 111   - SyncFirst
 112   - NoExtract
 113   - NoUpgrade
 114   - XferCommand
 115
 116 For documentation on these options, see the pacman.conf documentation.
 117
 118 Examples:
 119         self.option["NoUpgrade"] = ["etc/X11/xorg.conf",
 120                                     "etc/pacman.conf"]
 121         self.option["NoExtract"] = ["etc/lilo.conf"]
 122
 123         filesystem
 124         ----------
 125
 126 A list of strings describing a set of files supposed to exist in the filesystem
 127 when the test case is run.
 128 Upon test startup, pactest will automatically populate the test environment
 129 filesystem with this list of files.
 130
 131 Example:
 132         self.filesystem = ["bin/dummy",
 133                            "etc/X11/xorg.conf.pacsave"]
 134
 135 Note that all paths are relative ones, and thus file names should not start
 136 with a "/".
 137
 138
 139 Packages
 140 ========
 141
 142 The test case file description shall define a number of packages that can be
 143 used to either populate a database, or to feed pacman with data needed during
 144 its execution.
 145
 146 This can be achieved by creating pmpkg objects, with the following constructor:
 147   pmpkg(name, version)
 148
 149 Both "name" and "version" are strings.  Also, note that if not provided, the
 150 version defaults to "1.0-1".
 151
 152 Example:
 153         pkg1 = pmpkg("dummy", "2.1-1")
 154         pkg2 = pmpkg("foobar")
 155
 156 All fields from a ArchLinux package can be set and modified directly with no
 157 methods to access them.
 158 Note: some fields are automatically set by pactest and should preferably not
 159 be modified by hand (i.e. "md5sum", "size", or "csize").
 160
 161 Examples:
 162         pkg.depends = ["pkg2", "pkg3>=2.0"]
 163         pkg.files = ["bin/dummy", "etc/dummy.conf", "usr/man/man1/dummy.1"]
 164
 165
 166 Databases
 167 =========
 168
 169 The test environment provides a way to create and fill databases (local or
 170 sync ones).
 171
 172 The following methods shall be used:
 173
 174         * addpkg2db(database, package)
 175
 176 Notes: "database" is a string, and "package" shall be a previously created
 177 pmpkg object.
 178
 179 Examples:
 180         self.addpkg2db("local", lpkg)
 181         self.addpkg2db("sync1", spkg11)
 182         self.addpkg2db("sync1", spkg12)
 183         self.addpkg2db("sync2", spkg21)
 184
 185 Note: there is no need to explicitly create a database.  The "local" one
 186 already exists (even if empty), and sync databases are created on the fly when
 187 a new database new is given.
 188
 189         * addpkg(package)
 190
 191 package is an existing pmpkg object.
 192 It creates a package archive based on the given object.  The resulting archive
 193 is located in the temporary directory of the test environment, ready to be
 194 supplied to pacman for test purposes.
 195
 196
 197 Files
 198 =====
 199
 200 All files created by pactest are filled with a content defaulting to the file
 201 name, with an additional line feed.
 202 For instance, the content of a file "bin/dummy" created in the test environment
 203 file system is: "bin/dummy\n".
 204
 205 It is possible to create directories by appending a slash "/" to the name and
 206 to create symlinks by appending an arrow followed by a filename " -> target".
 207
 208 Note: only relative symlinks are supported.
 209
 210 Example:
 211         pkg = pmpkg("dummy")
 212         pkg.files = ["bin/dummy",
 213                      "usr/local/",
 214                      "lib/libfoo.so.O",
 215                      "lib/libfoo.so -> ./libfoo.so.0"]
 216
 217 In this example, "usr/local/" is a directory, and "libfoo.so" will be a
 218 symlink pointing at "libfoo.so.0".  It is usually a good idea to also define
 219 the target of the symlink!
 220
 221 It can be interesting for some tests to create altered files.  This can be
 222 done by appending one or more asterisks "*" to the file name.
 223
 224 Example:
 225         lpkg = pmpkg("dummy")
 226         lpkg.files = ["bin/dummy"]
 227         self.addpkg2db("local", lpkg)
 228
 229         newpkg = pmpkg("dummy", "1.0-2")
 230         newpkg.files = ["bin/dummy*"]
 231         self.addpkg(newpkg)
 232
 233         self.args = "-U dummy-1.0-2.pkg.tar.gz"
 234
 235 In this case, package "lpkg" will install a file "bin/dummy" with "bin/dummy\n"
 236 as its content.  Upon package upgrade, newpkg will provide a file named
 237 "bin/dummy" with "bin/dummy*\n" as its content.
 238 This is useful to simulate that a file has been modified between two different
 239 releases of a same package.
 240
 241 The same also applies to files from  the "filesystem" parameter of the test
 242 environment, and to the "backup" attribute of a package object.
 243
 244
 245 Rules
 246 =====
 247
 248 Finally, to check test success or failure, one shall define a set of rules.
 249
 250         addrule(rule)
 251         -------------
 252
 253 A rule is a string composed by a key and an item, joined with a "=" symbol.
 254
 255 Examples:
 256         self.addrule("PACMAN_RETCODE=0")
 257         self.addrule("PKG_EXIST=dummy")
 258         self.addrule("FILE_MODIFIED=bin/dummy")
 259         self.addrule("PKG_DEPENDS=xorg|fontconfig")
 260
 261 Note: an item can be divided into two arguments, as shown in the latter
 262 example.
 263
 264 All rules can be prepended with a bang "!" in order to tell pactest to expect
 265 the exact opposite result.
 266
 267 Example:
 268         self.addrule("!FILE_MODIFIED=bin/dummy")
 269
 270 Finally, the following rules are supported:
 271
 272         . PACMAN rules
 273
 274 Possible rules are:
 275
 276   PACMAN_RETCODE=value
 277   PACMAN_OUTPUT=value
 278
 279 For RETCODE, pactest will ensure the pacman return code is the value given.
 280 For OUTPUT, pactest will grep pacman outputs for the given value.
 281
 282 Note: PACMAN_OUTPUT should not be used. Pacman outputs are likely to change
 283 from one release to another, so that it's reliability is quite low.
 284
 285         . PKG rules
 286
 287 For each rule, pactest will read the entry "name" from the local database and
 288 challenge the requested data with it.
 289
 290 Possible rules are:
 291
 292   PKG_EXIST=name
 293   PKG_MODIFIED=name
 294   PKG_VERSION=name|version
 295   PKG_GROUPS=name|group
 296   PKG_PROVIDES=name|providename
 297   PKG_DEPENDS=name|depname
 298   PKG_OPTDEPENDS=name|depname
 299   PKG_REASON=name|intvalue
 300   PKG_FILES=name|filename
 301   PKG_BACKUP=name|backupname
 302
 303 Example:
 304         PKG_DEPENDS=ncurses|glibc
 305
 306 pactest will test to ensure the local database entry "ncurses" has "glibc" in
 307 its DEPENDS field.
 308
 309         . FILE rules
 310
 311   FILE_EXIST=path/to/file
 312   FILE_MODIFIED=path/to/file
 313   FILE_MODE=path/to/file|octal
 314   FILE_TYPE=path/to/file|type  (possible types: dir, file, link)
 315   FILE_PACNEW=path/to/file
 316   FILE_PACSAVE=path/to/file
 317   FILE_PACORIG=path/to/file
 318
 319 Example:
 320         FILE_EXIST=etc/test.conf
 321
 322 pactest will ensure the file /etc/test.conf exists in the filesystem.
 323