-
Notifications
You must be signed in to change notification settings - Fork 1
Paths
Handling of absolute and relative paths.
Exactly tries to be good at testing programs that operate on files and directories - creates, deletes, modifies or moves files, for example.
One feature designed to accomplish this is executing the [act] phase (the system under test) in a temporary sandbox directory, so that it will not pollute existing files and directories.
For this to work, the [setup] phase must be able to populate the sandbox with relevant files and directories, and to set the current working directory to one that is meaningful to the test.
Also, the [assert] phase must be able to look at the files in the sandbox and compare them with predefined files that represent expected outcome.
To accomplish this, it must be possible to refer to files in different locations.
It helps a lot if paths used during the execution of a test case are absolute, since that makes it possible to use a path no matter what the current directory happens to be.
On the other hand, paths in a test case file must not be absolute! A test case might be part of a source tree for the program it tests, and it is impossible to know where on the computer this source tree has been checked out. Or the source tree might be checked out in multiple locations, and of course, the test case should test the version of the program that is in the same source tree as the test case file itself.
(There are tools to help with such situations, like GNU autotools, that can search-replace path identifiers with absolute paths. But Exactly tries to avoid to force the use of such a tool, when it comes to executing Exactly tests.)
Exactly uses a mechanism called relativity roots to translate relative paths in the test case, to absolute paths during the execution of the test case.
One of these relativity roots is the act home root. This is where the [act] phase expects to find the program file that is tested.
Of course, this is relevant only if a program file is tested. If the test uses an "actor" that tests something else, this is irrelevant.
act home is specified relative to the location of the test case file. But during execution of the test case it is translated to an absolute path, so that the [act] phase can find it, no matter where the temporary sandbox is located.
Each relativity root has a corresponding
- command line option,
- predefined symbol,
- predefined environment variable.
The symbol and the environment variable have identical identifiers.
The relativity root can be specified for each instruction argument that is a path.
The following ways to supple the act relativity root for a file my-file
are equivalent
(the act root has, option "-rel-act" and identifier "EXACTLY_ACT"):
-rel-act my-file
-rel EXACTLY_ACT my-file
@[EXACTLY_ACT]@/my-file
Programs run as sub processes from the test case (except for the [act] phase), have access to the environment variable "EXACTLY_ACT".
Some instructions have a default relativity for some of its PATH arguments.
The reason is of course that the default is what expected to be the most common relativity, so that the option can be skipped to make the test case a bit more concise.
Check with each instruction to see if it uses a default relativity.
There are two "directory structures" that "contains" relativity roots:
A symbol defined as a "path" constitutes a kind of custom relativity root.
If the symbol MY_ROOT is defined as a path symbol, it may be used in the same way as the predefined path symbols:
-rel MY_ROOT file-in-my-root
@[MY_ROOT]@/file-in-my-root
(both specify the same path).
The custom root may build on an existing relativity root
def path MY_ROOT = -rel-act my-sub-dir-of-act/my-other-sub-dir
def path MY_ROOT = -rel MY_OTHER_ROOT my-sub-dir
def path MY_ROOT = @[MY_OTHER_ROOT]@/my-sub-dir
(the last two ones are equivalent)
or be a hard coded absolute path:
def path MY_ROOT = /usr/bin