CedarBackup2.testutil

Package CedarBackup2 :: Module testutil |
[hide private]
[frames] | no frames]

# Module testutil

source code

Provides unit-testing utilities.

These utilities are kept here, separate from util.py, because they provide common functionality that I do not want exported "publicly" once Cedar Backup is installed on a system. They are only used for unit testing, and are only useful within the source tree.

Many of these functions are in here because they are "good enough" for unit test work but are not robust enough to be real public functions. Others (like removedir) do what they are supposed to, but I don't want responsibility for making them available to others.

Author: Kenneth J. Pronovici <pronovic@ieee.org>

Functions | [hide private]
findResources(resources, dataDirs) Returns a dictionary of locations for various resources. | source code
commandAvailable(command) Indicates whether a command is available on $PATH somewhere. | source code
buildPath(components) Builds a complete path from a list of components. | source code
removedir(tree) Recursively removes an entire directory. | source code
extractTar(tmpdir, filepath) Extracts the indicated tar file to the indicated tmpdir. | source code
changeFileAge(filename, subtract=None) Changes a file age using the `os.utime` function. | source code
getMaskAsMode() Returns the user's current umask inverted to a mode. | source code
getLogin() Returns the name of the currently-logged in user. | source code
failUnlessAssignRaises(testCase, exception, obj, prop, value) Equivalent of `failUnlessRaises`, but used for property assignments instead. | source code
runningAsRoot() Returns boolean indicating whether the effective user id is root. | source code
platformDebian() Returns boolean indicating whether this is the Debian platform. | source code
platformMacOsX() Returns boolean indicating whether this is the Mac OS X platform. | source code
platformCygwin() Returns boolean indicating whether this is the Cygwin platform. | source code
platformWindows() Returns boolean indicating whether this is the Windows platform. | source code
platformHasEcho() Returns boolean indicating whether the platform has a sensible echo command. | source code
platformSupportsLinks() Returns boolean indicating whether the platform supports soft-links. | source code
platformSupportsPermissions() Returns boolean indicating whether the platform supports UNIX-style file permissions. | source code
platformRequiresBinaryRead() Returns boolean indicating whether the platform requires binary reads. | source code
setupDebugLogger() Sets up a screen logger for debugging purposes. | source code
setupOverrides() Set up any platform-specific overrides that might be required. | source code
randomFilename(length, prefix=None, suffix=None) Generates a random filename with the given length. | source code
captureOutput(c) Captures the output (stdout, stderr) of a function or a method. | source code
_isPlatform(name) Returns boolean indicating whether we're running on the indicated platform. | source code
availableLocales() Returns a list of available locales on the system | source code
hexFloatLiteralAllowed() Indicates whether hex float literals are allowed by the interpreter. | source code

Variables | [hide private]
| __package__ = ``'``CedarBackup2``'``

Function Details | [hide private]

### findResources(resources, dataDirs) | source code
Returns a dictionary of locations for various resources. Parameters: `resources` - List of required resources. `dataDirs` - List of data directories to search within for resources. Returns: Dictionary mapping resource name to resource path. Raises: `Exception` - If some resource cannot be found.

### commandAvailable(command) | source code
Indicates whether a command is available on $PATH somewhere. This should work on both Windows and UNIX platforms. Parameters: `command` - Commang to search for Returns: Boolean true/false depending on whether command is available.

### buildPath(components) | source code
Builds a complete path from a list of components. For instance, constructs `"/a/b/c"` from `["/a", "b", "c",]`. Parameters: `components` - List of components. Returns: String path constructed from components. Raises: `ValueError` - If a path cannot be encoded properly.

### removedir(tree) | source code
Recursively removes an entire directory. This is basically taken from an example on python.com. Parameters: `tree` - Directory tree to remove. Raises: `ValueError` - If a path cannot be encoded properly.

### extractTar(tmpdir, filepath) | source code
Extracts the indicated tar file to the indicated tmpdir. Parameters: `tmpdir` - Temp directory to extract to. `filepath` - Path to tarfile to extract. Raises: `ValueError` - If a path cannot be encoded properly.

### changeFileAge(filename, subtract=None) | source code
Changes a file age using the `os.utime` function. Parameters: `filename` - File to operate on. `subtract` - Number of seconds to subtract from the current time. Raises: `ValueError` - If a path cannot be encoded properly. Note: Some platforms don't seem to be able to set an age precisely. As a result, whereas we might have intended to set an age of 86400 seconds, we actually get an age of 86399.375 seconds. When util.calculateFileAge() looks at that the file, it calculates an age of 0.999992766204 days, which then gets truncated down to zero whole days. The tests get very confused. To work around this, I always subtract off one additional second as a fudge factor. That way, the file age will be at least as old as requested later on.

### getMaskAsMode() | source code
Returns the user's current umask inverted to a mode. A mode is mostly a bitwise inversion of a mask, i.e. mask 002 is mode 775. Returns: Umask converted to a mode, as an integer.

### getLogin() | source code
Returns the name of the currently-logged in user. This might fail under some circumstances - but if it does, our tests would fail anyway.

### failUnlessAssignRaises(testCase, exception, obj, prop, value) | source code
Equivalent of `failUnlessRaises`, but used for property assignments instead. It's nice to be able to use `failUnlessRaises` to check that a method call raises the exception that you expect. Unfortunately, this method can't be used to check Python propery assignments, even though these property assignments are actually implemented underneath as methods. This function (which can be easily called by unit test classes) provides an easy way to wrap the assignment checks. It's not pretty, or as intuitive as the original check it's modeled on, but it does work. Let's assume you make this method call:
      testCase.failUnlessAssignRaises(ValueError, collectDir, "absolutePath", absolutePath)
If you do this, a test case failure will be raised unless the assignment:
      collectDir.absolutePath = absolutePath
fails with a `ValueError` exception. The failure message differentiates between the case where no exception was raised and the case where the wrong exception was raised. Parameters: `testCase` - PyUnit test case object (i.e. self). `exception` - Exception that is expected to be raised. `obj` - Object whose property is to be assigned to. `prop` - Name of the property, as a string. `value` - Value that is to be assigned to the property. Note: Internally, the `missed` and `instead` variables are used rather than directly calling `testCase.fail` upon noticing a problem because the act of "failure" itself generates an exception that would be caught by the general `except` clause. See Also: `unittest.TestCase.failUnlessRaises`

### runningAsRoot() | source code
Returns boolean indicating whether the effective user id is root. This is always true on platforms that have no concept of root, like Windows.

### platformHasEcho() | source code
Returns boolean indicating whether the platform has a sensible echo command. On some platforms, like Windows, echo doesn't really work for tests.

### platformSupportsLinks() | source code
Returns boolean indicating whether the platform supports soft-links. Some platforms, like Windows, do not support links, and tests need to take this into account.

### platformSupportsPermissions() | source code
Returns boolean indicating whether the platform supports UNIX-style file permissions. Some platforms, like Windows, do not support permissions, and tests need to take this into account.

### platformRequiresBinaryRead() | source code
Returns boolean indicating whether the platform requires binary reads. Some platforms, like Windows, require a special flag to read binary data from files.

### setupDebugLogger() | source code
Sets up a screen logger for debugging purposes. Normally, the CLI functionality configures the logger so that things get written to the right place. However, for debugging it's sometimes nice to just get everything -- debug information and output -- dumped to the screen. This function takes care of that.

### setupOverrides() | source code
Set up any platform-specific overrides that might be required. When packages are built, this is done manually (hardcoded) in customize.py and the overrides are set up in cli.cli(). This way, no runtime checks need to be done. This is safe, because the package maintainer knows exactly which platform (Debian or not) the package is being built for. Unit tests are different, because they might be run anywhere. So, we attempt to make a guess about plaform using platformDebian(), and use that to set up the custom overrides so that platform-specific unit tests continue to work.

### randomFilename(length, prefix=None, suffix=None) | source code
Generates a random filename with the given length. Parameters: `length` - Length of filename. @return Random filename.

### captureOutput(c) | source code
Captures the output (stdout, stderr) of a function or a method. Some of our functions don't do anything other than just print output. We need a way to test these functions (at least nominally) but we don't want any of the output spoiling the test suite output. This function just creates a dummy file descriptor that can be used as a target by the callable function, rather than `stdout` or `stderr`. Parameters: `c` - Callable function or method. Returns: Output of function, as one big string. Note: This method assumes that `callable` doesn't take any arguments besides keyword argument `fd` to specify the file descriptor.

### _isPlatform(name) | source code
Returns boolean indicating whether we're running on the indicated platform. Parameters: `name` - Platform name to check, currently one of "windows" or "macosx"

### availableLocales() | source code
Returns a list of available locales on the system Returns: List of string locale names

### hexFloatLiteralAllowed() | source code
Indicates whether hex float literals are allowed by the interpreter. As far back as 2004, some Python documentation indicated that octal and hex notation applied only to integer literals. However, prior to Python 2.5, it was legal to construct a float with an argument like 0xAC on some platforms. This check provides a an indication of whether the current interpreter supports that behavior. This check exists so that unit tests can continue to test the same thing as always for pre-2.5 interpreters (i.e. making sure backwards compatibility doesn't break) while still continuing to work for later interpreters. The returned value is True if hex float literals are allowed, False otherwise.