diff --git a/test/pacman/README b/test/pacman/README index e6fc210b..10f0ff2b 100644 --- a/test/pacman/README +++ b/test/pacman/README @@ -4,17 +4,17 @@ README pactest is a test suite for the Arch Linux 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 +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 +It is written in Python and makes available most of what can be found in pacman's code to create Arch Linux packages or read and write databases entries. -Each test case is defined in a separate file that is sourced in order to set +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 +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) @@ -23,7 +23,7 @@ The following directory structure is used: - var/log/pactest.log: log file - var/pub: location for pseudo sync repositories - tmp: hold all local package archives (to be used with pacman -U) - + Note: the logfile is used to capture all pacman outputs. Test case example: @@ -41,7 +41,7 @@ Test case example: 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), +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 -U" Upon completion, it checks that: - pacman returned no error code, @@ -84,13 +84,13 @@ 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 +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 +A string of arguments that are passed to the pacman binary when the test is run. Example: @@ -119,30 +119,30 @@ Examples: filesystem ---------- -A list of strings describing a set of files supposed to exist in the 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 +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 +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 +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 +Both "name" and "version" are strings. Also, note that if not provided, the version defaults to "1.0-1". Example: @@ -151,7 +151,7 @@ Example: All fields from a Arch Linux 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 +Note: some fields are automatically set by pactest and should preferably not be modified by hand (i.e. "md5sum", "size", or "csize"). Examples: @@ -162,14 +162,14 @@ Examples: Databases ========= -The test environment provides a way to create and fill databases (local or +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 +Notes: "database" is a string, and "package" shall be a previously created pmpkg object. Examples: @@ -178,15 +178,15 @@ Examples: 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 +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 name 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 +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. @@ -198,7 +198,7 @@ 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 +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. @@ -210,11 +210,11 @@ Example: "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 +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 +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: @@ -228,13 +228,13 @@ Example: 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 +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 +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 +The same also applies to files from the "filesystem" parameter of the test environment, and to the "backup" attribute of a package object. @@ -254,10 +254,10 @@ Examples: 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 +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 +All rules can be prepended with a bang "!" in order to tell pactest to expect the exact opposite result. Example: @@ -275,12 +275,12 @@ Possible rules are: 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 +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 +For each rule, pactest will read the entry "name" from the local database and challenge the requested data with it. Possible rules are: