gcloud 0.0.2 → 0.0.4

data/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/basetest.py

@@ -0,0 +1,1260 @@
+#!/usr/bin/env python
+# Copyright 2010 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS-IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Base functionality for google tests.
+
+This module contains base classes and high-level functions for Google-style
+tests.
+"""
+
+__author__ = 'dborowitz@google.com (Dave Borowitz)'
+
+import commands
+import difflib
+import getpass
+import itertools
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import types
+
+
+# unittest2 is a backport of Python 2.7's unittest for Python 2.6, so
+# we don't need it if we are running 2.7 or newer.
+
+if sys.version_info < (2, 7):
+  import unittest2 as unittest
+else:
+  import unittest
+
+from google.apputils import app
+import gflags as flags
+from google.apputils import shellutil
+
+FLAGS = flags.FLAGS
+
+# ----------------------------------------------------------------------
+# Internal functions to extract default flag values from environment.
+# ----------------------------------------------------------------------
+def _GetDefaultTestRandomSeed():
+  random_seed = 301
+  value = os.environ.get('TEST_RANDOM_SEED', '')
+  try:
+    random_seed = int(value)
+  except ValueError:
+    pass
+  return random_seed
+
+
+def _GetDefaultTestTmpdir():
+  tmpdir = os.environ.get('TEST_TMPDIR', '')
+  if not tmpdir:
+    tmpdir = os.path.join(tempfile.gettempdir(), 'google_apputils_basetest')
+
+  return tmpdir
+
+
+flags.DEFINE_integer('test_random_seed', _GetDefaultTestRandomSeed(),
+                     'Random seed for testing. Some test frameworks may '
+                     'change the default value of this flag between runs, so '
+                     'it is not appropriate for seeding probabilistic tests.',
+                     allow_override=1)
+flags.DEFINE_string('test_srcdir',
+                    os.environ.get('TEST_SRCDIR', ''),
+                    'Root of directory tree where source files live',
+                    allow_override=1)
+flags.DEFINE_string('test_tmpdir', _GetDefaultTestTmpdir(),
+                    'Directory for temporary testing files',
+                    allow_override=1)
+
+
+class BeforeAfterTestCaseMeta(type):
+
+  """Adds setUpTestCase() and tearDownTestCase() methods.
+
+  These may be needed for setup and teardown of shared fixtures usually because
+  such fixtures are expensive to setup and teardown (eg Perforce clients).  When
+  using such fixtures, care should be taken to keep each test as independent as
+  possible (eg via the use of sandboxes).
+
+  Example:
+
+    class MyTestCase(basetest.TestCase):
+
+      __metaclass__ = basetest.BeforeAfterTestCaseMeta
+
+      @classmethod
+      def setUpTestCase(cls):
+        cls._resource = foo.ReallyExpensiveResource()
+
+      @classmethod
+      def tearDownTestCase(cls):
+        cls._resource.Destroy()
+
+      def testSomething(self):
+        self._resource.Something()
+        ...
+  """
+
+  _test_loader = unittest.defaultTestLoader
+
+  def __init__(cls, name, bases, dict):
+    super(BeforeAfterTestCaseMeta, cls).__init__(name, bases, dict)
+
+    # Notes from mtklein
+
+    # This code can be tricky to think about.  Here are a few things to remember
+    # as you read through it.
+
+    # When inheritance is involved, this __init__ is called once on each class
+    # in the inheritance chain when that class is defined.  In a typical
+    # scenario where a BaseClass inheriting from TestCase declares the
+    # __metaclass__ and SubClass inherits from BaseClass, __init__ will be first
+    # called with cls=BaseClass when BaseClass is defined, and then called later
+    # with cls=SubClass when SubClass is defined.
+
+    # To know when to call setUpTestCase and tearDownTestCase, this class wraps
+    # the setUp, tearDown, and test* methods in a TestClass.  We'd like to only
+    # wrap those methods in the leaves of the inheritance tree, but we can't
+    # know when we're a leaf at wrapping time.  So instead we wrap all the
+    # setUp, tearDown, and test* methods, but code them so that we only do the
+    # counting we want at the leaves, which we *can* detect when we've got an
+    # actual instance to look at --- i.e. self, when a method is running.
+
+    # Because we're wrapping at every level of inheritance, some methods get
+    # wrapped multiple times down the inheritance chain; if SubClass were to
+    # inherit, say, setUp or testFoo from BaseClass, that method would be
+    # wrapped twice, first by BaseClass then by SubClass.  That's OK, because we
+    # ensure that the extra code we inject with these wrappers is idempotent.
+
+    # test_names are the test methods this class can see.
+    test_names = set(cls._test_loader.getTestCaseNames(cls))
+
+    # Each class keeps a set of the tests it still has to run.  When it's empty,
+    # we know we should call tearDownTestCase.  For now, it holds the sentinel
+    # value of None, acting as a indication that we need to call setUpTestCase,
+    # which fills in the actual tests to run.
+    cls.__tests_to_run = None
+
+    # These calls go through and monkeypatch various methods, in no particular
+    # order.
+    BeforeAfterTestCaseMeta.SetSetUpAttr(cls, test_names)
+    BeforeAfterTestCaseMeta.SetTearDownAttr(cls)
+    BeforeAfterTestCaseMeta.SetTestMethodAttrs(cls, test_names)
+    BeforeAfterTestCaseMeta.SetBeforeAfterTestCaseAttr()
+
+  # Just a little utility function to help with monkey-patching.
+  @staticmethod
+  def SetMethod(cls, method_name, replacement):
+    """Like setattr, but also preserves name, doc, and module metadata."""
+    original = getattr(cls, method_name)
+    replacement.__name__ = original.__name__
+    replacement.__doc__ = original.__doc__
+    replacement.__module__ = original.__module__
+    setattr(cls, method_name, replacement)
+
+  @staticmethod
+  def SetSetUpAttr(cls, test_names):
+    """Wraps setUp() with per-class setUp() functionality."""
+    # Remember that SetSetUpAttr is eventually called on each class in the
+    # inheritance chain.  This line can be subtle because of inheritance.  Say
+    # we've got BaseClass that defines setUp, and SubClass inheriting from it
+    # that doesn't define setUp.  This method will run twice, and both times
+    # cls_setUp will be BaseClass.setUp.  This is one of the tricky cases where
+    # setUp will be wrapped multiple times.
+    cls_setUp = cls.setUp
+
+    # We create a new setUp method that first checks to see if we need to run
+    # setUpTestCase (looking for the __tests_to_run==None flag), and then runs
+    # the original setUp method.
+    def setUp(self):
+      """Function that will encapsulate and replace cls.setUp()."""
+      # This line is unassuming but crucial to making this whole system work.
+      # It sets leaf to the class of the instance we're currently testing.  That
+      # is, leaf is going to be a leaf class.  It's not necessarily the same
+      # class as the parameter cls that's being passed in.  For example, in the
+      # case above where setUp is in BaseClass, when we instantiate a SubClass
+      # and call setUp, we need leaf to be pointing at the class SubClass.
+      leaf = self.__class__
+
+      # The reason we want to do this is that it makes sure setUpTestCase is
+      # only run once, not once for each class down the inheritance chain.  When
+      # multiply-wrapped, this extra code is called multiple times.  In the
+      # running example:
+      #
+      #  1) cls=BaseClass: replace BaseClass' setUp with a wrapped setUp
+      #  2) cls=SubClass: set SubClass.setUp to what it thinks was its original
+      #     setUp --- the wrapped setUp from 1)
+      #
+      # So it's double-wrapped, but that's OK.  When we actually call setUp from
+      # an instance, we're calling the double-wrapped method.  It sees
+      # __tests_to_run is None and fills that in.  Then it calls what it thinks
+      # was its original setUp, the singly-wrapped setUp from BaseClass.  The
+      # singly-wrapped setUp *skips* the if-statement, as it sees
+      # leaf.__tests_to_run is not None now.  It just runs the real, original
+      # setUp().
+
+      # test_names is passed in from __init__, and holds all the test cases that
+      # cls can see.  In the BaseClass call, that's probably the empty set, and
+      # for SubClass it'd have your test methods.
+
+      if leaf.__tests_to_run is None:
+        leaf.__tests_to_run = set(test_names)
+        self.setUpTestCase()
+      cls_setUp(self)
+
+    # Monkeypatch our new setUp method into the place of the original.
+    BeforeAfterTestCaseMeta.SetMethod(cls, 'setUp', setUp)
+
+  @staticmethod
+  def SetTearDownAttr(cls):
+    """Wraps tearDown() with per-class tearDown() functionality."""
+
+    # This is analagous to SetSetUpAttr, except of course it's patching tearDown
+    # to run tearDownTestCase when there are no more tests to run.  All the same
+    # hairy logic applies.
+    cls_tearDown = cls.tearDown
+
+    def tearDown(self):
+      """Function that will encapsulate and replace cls.tearDown()."""
+      cls_tearDown(self)
+
+      leaf = self.__class__
+      # We need to make sure that tearDownTestCase is only run when
+      # we're executing this in the leaf class, so we need the
+      # explicit leaf == cls check below.
+      if (leaf.__tests_to_run is not None
+          and not leaf.__tests_to_run
+          and leaf == cls):
+        leaf.__tests_to_run = None
+        self.tearDownTestCase()
+
+    BeforeAfterTestCaseMeta.SetMethod(cls, 'tearDown', tearDown)
+
+  @staticmethod
+  def SetTestMethodAttrs(cls, test_names):
+    """Makes each test method first remove itself from the remaining set."""
+    # This makes each test case remove itself from the set of remaining tests.
+    # You might think that this belongs more logically in tearDown, and I'd
+    # agree except that tearDown doesn't know what test case it's tearing down!
+    # Instead we have the test method itself remove itself before attempting the
+    # test.
+
+    # Note that having the test remove itself after running doesn't work, as we
+    # never get to 'after running' for tests that fail.
+
+    # Like setUp and tearDown, the test case could conceivably be wrapped
+    # twice... but as noted it's an implausible situation to have an actual test
+    # defined in a base class.  Just in case, we take the same precaution by
+    # looking in only the leaf class' set of __tests_to_run, and using discard()
+    # instead of remove() to make the operation idempotent.
+
+    for test_name in test_names:
+      cls_test = getattr(cls, test_name)
+
+      # The default parameters here make sure that each new test() function
+      # remembers its own values of cls_test and test_name.  Without these
+      # default parameters, they'd all point to the values from the last
+      # iteration of the loop, causing some arbitrary test method to run
+      # multiple times and the others never. :(
+      def test(self, cls_test=cls_test, test_name=test_name):
+        leaf = self.__class__
+        leaf.__tests_to_run.discard(test_name)
+        return cls_test(self)
+
+      BeforeAfterTestCaseMeta.SetMethod(cls, test_name, test)
+
+  @staticmethod
+  def SetBeforeAfterTestCaseAttr():
+    # This just makes sure every TestCase has a setUpTestCase or
+    # tearDownTestCase, so that you can safely define only one or neither of
+    # them if you want.
+    TestCase.setUpTestCase = lambda self: None
+    TestCase.tearDownTestCase = lambda self: None
+
+
+class TestCase(unittest.TestCase):
+  """Extension of unittest.TestCase providing more powerful assertions."""
+
+  maxDiff = 80 * 20
+
+  def __init__(self, methodName='runTest'):
+    super(TestCase, self).__init__(methodName)
+    self.__recorded_properties = {}
+
+  def shortDescription(self):
+    """Format both the test method name and the first line of its docstring.
+
+    If no docstring is given, only returns the method name.
+
+    This method overrides unittest.TestCase.shortDescription(), which
+    only returns the first line of the docstring, obscuring the name
+    of the test upon failure.
+
+    Returns:
+      desc: A short description of a test method.
+    """
+    desc = str(self)
+    # NOTE: super() is used here instead of directly invoking
+    # unittest.TestCase.shortDescription(self), because of the
+    # following line that occurs later on:
+    #       unittest.TestCase = TestCase
+    # Because of this, direct invocation of what we think is the
+    # superclass will actually cause infinite recursion.
+    doc_first_line = super(TestCase, self).shortDescription()
+    if doc_first_line is not None:
+      desc = '\n'.join((desc, doc_first_line))
+    return desc
+
+  def assertSequenceStartsWith(self, prefix, whole, msg=None):
+    """An equality assertion for the beginning of ordered sequences.
+
+    If prefix is an empty sequence, it will raise an error unless whole is also
+    an empty sequence.
+
+    If prefix is not a sequence, it will raise an error if the first element of
+    whole does not match.
+
+    Args:
+      prefix: A sequence expected at the beginning of the whole parameter.
+      whole: The sequence in which to look for prefix.
+      msg: Optional message to append on failure.
+    """
+    try:
+      prefix_len = len(prefix)
+    except (TypeError, NotImplementedError):
+      prefix = [prefix]
+      prefix_len = 1
+
+    try:
+      whole_len = len(whole)
+    except (TypeError, NotImplementedError):
+      self.fail('For whole: len(%s) is not supported, it appears to be type: '
+                '%s' % (whole, type(whole)))
+
+    assert prefix_len <= whole_len, (
+        'Prefix length (%d) is longer than whole length (%d).' %
+        (prefix_len, whole_len))
+
+    if not prefix_len and whole_len:
+      self.fail('Prefix length is 0 but whole length is %d: %s' %
+                (len(whole), whole))
+
+    try:
+      self.assertSequenceEqual(prefix, whole[:prefix_len], msg)
+    except AssertionError:
+      self.fail(msg or 'prefix: %s not found at start of whole: %s.' %
+                (prefix, whole))
+
+  def assertContainsSubset(self, expected_subset, actual_set, msg=None):
+    """Checks whether actual iterable is a superset of expected iterable."""
+    missing = set(expected_subset) - set(actual_set)
+    if not missing:
+      return
+
+    missing_msg = 'Missing elements %s\nExpected: %s\nActual: %s' % (
+        missing, expected_subset, actual_set)
+    if msg:
+      msg += ': %s' % missing_msg
+    else:
+      msg = missing_msg
+    self.fail(msg)
+
+  def assertSameElements(self, expected_seq, actual_seq, msg=None):
+    """Assert that two sequences have the same elements (in any order).
+
+    This method, unlike assertItemsEqual, doesn't care about any
+    duplicates in the expected and actual sequences.
+
+      >> assertSameElements([1, 1, 1, 0, 0, 0], [0, 1])
+      # Doesn't raise an AssertionError
+
+    If possible, you should use assertItemsEqual instead of
+    assertSameElements.
+
+    Args:
+      expected_seq: A sequence containing elements we are expecting.
+      actual_seq: The sequence that we are testing.
+      msg: The message to be printed if the test fails.
+    """
+    # `unittest2.TestCase` used to have assertSameElements, but it was
+    # removed in favor of assertItemsEqual. As there's a unit test
+    # that explicitly checks this behavior, I am leaving this method
+    # alone.
+    try:
+      expected = dict([(element, None) for element in expected_seq])
+      actual = dict([(element, None) for element in actual_seq])
+      missing = [element for element in expected if element not in actual]
+      unexpected = [element for element in actual if element not in expected]
+      missing.sort()
+      unexpected.sort()
+    except TypeError:
+      # Fall back to slower list-compare if any of the objects are
+      # not hashable.
+      expected = list(expected_seq)
+      actual = list(actual_seq)
+      expected.sort()
+      actual.sort()
+      missing, unexpected = _SortedListDifference(expected, actual)
+    errors = []
+    if missing:
+      errors.append('Expected, but missing:\n  %r\n' % missing)
+    if unexpected:
+      errors.append('Unexpected, but present:\n  %r\n' % unexpected)
+    if errors:
+      self.fail(msg or ''.join(errors))
+
+  # unittest2.TestCase.assertMulitilineEqual works very similarly, but it
+  # has a different error format. However, I find this slightly more readable.
+  def assertMultiLineEqual(self, first, second, msg=None):
+    """Assert that two multi-line strings are equal."""
+    assert isinstance(first, types.StringTypes), (
+        'First argument is not a string: %r' % (first,))
+    assert isinstance(second, types.StringTypes), (
+        'Second argument is not a string: %r' % (second,))
+
+    if first == second:
+      return
+    if msg:
+      raise self.failureException(msg)
+
+    failure_message = ['\n']
+    for line in difflib.ndiff(first.splitlines(True), second.splitlines(True)):
+      failure_message.append(line)
+      if not line.endswith('\n'):
+        failure_message.append('\n')
+    raise self.failureException(''.join(failure_message))
+
+  def assertBetween(self, value, minv, maxv, msg=None):
+    """Asserts that value is between minv and maxv (inclusive)."""
+    if msg is None:
+      msg = '"%r" unexpectedly not between "%r" and "%r"' % (value, minv, maxv)
+    self.assert_(minv <= value, msg)
+    self.assert_(maxv >= value, msg)
+
+  def assertRegexMatch(self, actual_str, regexes, message=None):
+    """Asserts that at least one regex in regexes matches str.
+
+    If possible you should use assertRegexpMatches, which is a simpler
+    version of this method. assertRegexpMatches takes a single regular
+    expression (a string or re compiled object) instead of a list.
+
+    Notes:
+    1. This function uses substring matching, i.e. the matching
+       succeeds if *any* substring of the error message matches *any*
+       regex in the list.  This is more convenient for the user than
+       full-string matching.
+
+    2. If regexes is the empty list, the matching will always fail.
+
+    3. Use regexes=[''] for a regex that will always pass.
+
+    4. '.' matches any single character *except* the newline.  To
+       match any character, use '(.|\n)'.
+
+    5. '^' matches the beginning of each line, not just the beginning
+       of the string.  Similarly, '$' matches the end of each line.
+
+    6. An exception will be thrown if regexes contains an invalid
+       regex.
+
+    Args:
+      actual_str:  The string we try to match with the items in regexes.
+      regexes:  The regular expressions we want to match against str.
+        See "Notes" above for detailed notes on how this is interpreted.
+      message:  The message to be printed if the test fails.
+    """
+    if isinstance(regexes, basestring):
+      self.fail('regexes is a string; it needs to be a list of strings.')
+    if not regexes:
+      self.fail('No regexes specified.')
+
+    regex = '(?:%s)' % ')|(?:'.join(regexes)
+
+    if not re.search(regex, actual_str, re.MULTILINE):
+      self.fail(message or ('String "%s" does not contain any of these '
+                            'regexes: %s.' % (actual_str, regexes)))
+
+  def assertCommandSucceeds(self, command, regexes=[''], env=None,
+                            close_fds=True):
+    """Asserts that a shell command succeeds (i.e. exits with code 0).
+
+    Args:
+      command: List or string representing the command to run.
+      regexes: List of regular expression strings.
+      env: Dictionary of environment variable settings.
+      close_fds: Whether or not to close all open fd's in the child after
+        forking.
+    """
+    (ret_code, err) = GetCommandStderr(command, env, close_fds)
+
+    command_string = GetCommandString(command)
+    self.assert_(
+        ret_code == 0,
+        'Running command\n'
+        '%s failed with error code %s and message\n'
+        '%s' % (
+            _QuoteLongString(command_string),
+            ret_code,
+            _QuoteLongString(err)))
+    self.assertRegexMatch(
+        err,
+        regexes,
+        message=(
+            'Running command\n'
+            '%s failed with error code %s and message\n'
+            '%s which matches no regex in %s' % (
+                _QuoteLongString(command_string),
+                ret_code,
+                _QuoteLongString(err),
+                regexes)))
+
+  def assertCommandFails(self, command, regexes, env=None, close_fds=True):
+    """Asserts a shell command fails and the error matches a regex in a list.
+
+    Args:
+      command: List or string representing the command to run.
+      regexes: the list of regular expression strings.
+      env: Dictionary of environment variable settings.
+      close_fds: Whether or not to close all open fd's in the child after
+        forking.
+    """
+    (ret_code, err) = GetCommandStderr(command, env, close_fds)
+
+    command_string = GetCommandString(command)
+    self.assert_(
+        ret_code != 0,
+        'The following command succeeded while expected to fail:\n%s' %
+        _QuoteLongString(command_string))
+    self.assertRegexMatch(
+        err,
+        regexes,
+        message=(
+            'Running command\n'
+            '%s failed with error code %s and message\n'
+            '%s which matches no regex in %s' % (
+                _QuoteLongString(command_string),
+                ret_code,
+                _QuoteLongString(err),
+                regexes)))
+
+  def assertRaisesWithPredicateMatch(self, expected_exception, predicate,
+                                     callable_obj, *args,
+                                     **kwargs):
+    """Asserts that exception is thrown and predicate(exception) is true.
+
+    Args:
+      expected_exception: Exception class expected to be raised.
+      predicate: Function of one argument that inspects the passed-in exception
+        and returns True (success) or False (please fail the test).
+      callable_obj: Function to be called.
+      args: Extra args.
+      kwargs: Extra keyword args.
+    """
+    try:
+      callable_obj(*args, **kwargs)
+    except expected_exception, err:
+      self.assert_(predicate(err),
+                   '%r does not match predicate %r' % (err, predicate))
+    else:
+      self.fail(expected_exception.__name__ + ' not raised')
+
+  def assertRaisesWithLiteralMatch(self, expected_exception,
+                                   expected_exception_message, callable_obj,
+                                   *args, **kwargs):
+    """Asserts that the message in a raised exception equals the given string.
+
+    Unlike assertRaisesWithRegexpMatch this method takes a literal string, not
+    a regular expression.
+
+    Args:
+      expected_exception: Exception class expected to be raised.
+      expected_exception_message: String message expected in the raised
+        exception.  For a raise exception e, expected_exception_message must
+        equal str(e).
+      callable_obj: Function to be called.
+      args: Extra args.
+      kwargs: Extra kwargs.
+    """
+    try:
+      callable_obj(*args, **kwargs)
+    except expected_exception, err:
+      actual_exception_message = str(err)
+      self.assert_(expected_exception_message == actual_exception_message,
+                   'Exception message does not match.\n'
+                   'Expected: %r\n'
+                   'Actual: %r' % (expected_exception_message,
+                                   actual_exception_message))
+    else:
+      self.fail(expected_exception.__name__ + ' not raised')
+
+  def assertRaisesWithRegexpMatch(self, expected_exception, expected_regexp,
+                                  callable_obj, *args, **kwargs):
+    """Asserts that the message in a raised exception matches the given regexp.
+
+    This is just a wrapper around assertRaisesRegexp. Please use
+    assertRaisesRegexp instead of assertRaisesWithRegexpMatch.
+
+    Args:
+      expected_exception: Exception class expected to be raised.
+      expected_regexp: Regexp (re pattern object or string) expected to be
+        found in error message.
+      callable_obj: Function to be called.
+      args: Extra args.
+      kwargs: Extra keyword args.
+    """
+    # TODO(user): this is a good candidate for a global
+    # search-and-replace.
+    self.assertRaisesRegexp(
+        expected_exception,
+        expected_regexp,
+        callable_obj,
+        *args,
+        **kwargs)
+
+  def assertContainsInOrder(self, strings, target):
+    """Asserts that the strings provided are found in the target in order.
+
+    This may be useful for checking HTML output.
+
+    Args:
+      strings: A list of strings, such as [ 'fox', 'dog' ]
+      target: A target string in which to look for the strings, such as
+        'The quick brown fox jumped over the lazy dog'.
+    """
+    if not isinstance(strings, list):
+      strings = [strings]
+
+    current_index = 0
+    last_string = None
+    for string in strings:
+      index = target.find(str(string), current_index)
+      if index == -1 and current_index == 0:
+        self.fail("Did not find '%s' in '%s'" %
+                  (string, target))
+      elif index == -1:
+        self.fail("Did not find '%s' after '%s' in '%s'" %
+                  (string, last_string, target))
+      last_string = string
+      current_index = index
+
+  def assertTotallyOrdered(self, *groups):
+    """Asserts that total ordering has been implemented correctly.
+
+    For example, say you have a class A that compares only on its attribute x.
+    Comparators other than __lt__ are omitted for brevity.
+
+    class A(object):
+      def __init__(self, x, y):
+        self.x = xio
+        self.y = y
+
+      def __hash__(self):
+        return hash(self.x)
+
+      def __lt__(self, other):
+        try:
+          return self.x < other.x
+        except AttributeError:
+          return NotImplemented
+
+    assertTotallyOrdered will check that instances can be ordered correctly.
+    For example,
+
+    self.assertTotallyOrdered(
+      [None],  # None should come before everything else.
+      [1],     # Integers sort earlier.
+      ['foo'],  # As do strings.
+      [A(1, 'a')],
+      [A(2, 'b')],  # 2 is after 1.
+      [A(2, 'c'), A(2, 'd')],  # The second argument is irrelevant.
+      [A(3, 'z')])
+
+    Args:
+     groups: A list of groups of elements.  Each group of elements is a list
+       of objects that are equal.  The elements in each group must be less than
+       the elements in the group after it.  For example, these groups are
+       totally ordered: [None], [1], [2, 2], [3].
+    """
+
+    def CheckOrder(small, big):
+      """Ensures small is ordered before big."""
+      self.assertFalse(small == big,
+                       '%r unexpectedly equals %r' % (small, big))
+      self.assertTrue(small != big,
+                      '%r unexpectedly equals %r' % (small, big))
+      self.assertLess(small, big)
+      self.assertFalse(big < small,
+                       '%r unexpectedly less than %r' % (big, small))
+      self.assertLessEqual(small, big)
+      self.assertFalse(big <= small,
+                       '%r unexpectedly less than or equal to %r'
+                       % (big, small))
+      self.assertGreater(big, small)
+      self.assertFalse(small > big,
+                       '%r unexpectedly greater than %r' % (small, big))
+      self.assertGreaterEqual(big, small)
+      self.assertFalse(small >= big,
+                       '%r unexpectedly greater than or equal to %r'
+                       % (small, big))
+
+    def CheckEqual(a, b):
+      """Ensures that a and b are equal."""
+      self.assertEqual(a, b)
+      self.assertFalse(a != b, '%r unexpectedly equals %r' % (a, b))
+      self.assertEqual(hash(a), hash(b),
+                       'hash %d of %r unexpectedly not equal to hash %d of %r'
+                       % (hash(a), a, hash(b), b))
+      self.assertFalse(a < b, '%r unexpectedly less than %r' % (a, b))
+      self.assertFalse(b < a, '%r unexpectedly less than %r' % (b, a))
+      self.assertLessEqual(a, b)
+      self.assertLessEqual(b, a)
+      self.assertFalse(a > b, '%r unexpectedly greater than %r' % (a, b))
+      self.assertFalse(b > a, '%r unexpectedly greater than %r' % (b, a))
+      self.assertGreaterEqual(a, b)
+      self.assertGreaterEqual(b, a)
+
+    # For every combination of elements, check the order of every pair of
+    # elements.
+    for elements in itertools.product(*groups):
+      elements = list(elements)
+      for index, small in enumerate(elements[:-1]):
+        for big in elements[index + 1:]:
+          CheckOrder(small, big)
+
+    # Check that every element in each group is equal.
+    for group in groups:
+      for a in group:
+        CheckEqual(a, a)
+      for a, b in itertools.product(group, group):
+        CheckEqual(a, b)
+
+  def getRecordedProperties(self):
+    """Return any properties that the user has recorded."""
+    return self.__recorded_properties
+
+  def recordProperty(self, property_name, property_value):
+    """Record an arbitrary property for later use.
+
+    Args:
+      property_name: str, name of property to record; must be a valid XML
+        attribute name
+      property_value: value of property; must be valid XML attribute value
+    """
+    self.__recorded_properties[property_name] = property_value
+
+  def _getAssertEqualityFunc(self, first, second):
+    try:
+      return super(TestCase, self)._getAssertEqualityFunc(first, second)
+    except AttributeError:
+      # This happens if unittest2.TestCase.__init__ was never run. It
+      # usually means that somebody created a subclass just for the
+      # assertions and has overriden __init__. "assertTrue" is a safe
+      # value that will not make __init__ raise a ValueError (this is
+      # a bit hacky).
+      test_method = getattr(self, '_testMethodName', 'assertTrue')
+      super(TestCase, self).__init__(test_method)
+
+    return super(TestCase, self)._getAssertEqualityFunc(first, second)
+
+
+# This is not really needed here, but some unrelated code calls this
+# function.
+# TODO(user): sort it out.
+def _SortedListDifference(expected, actual):
+  """Finds elements in only one or the other of two, sorted input lists.
+
+  Returns a two-element tuple of lists.  The first list contains those
+  elements in the "expected" list but not in the "actual" list, and the
+  second contains those elements in the "actual" list but not in the
+  "expected" list.  Duplicate elements in either input list are ignored.
+
+  Args:
+    expected:  The list we expected.
+    actual:  The list we actualy got.
+  Returns:
+    (missing, unexpected)
+    missing: items in expected that are not in actual.
+    unexpected: items in actual that are not in expected.
+  """
+  i = j = 0
+  missing = []
+  unexpected = []
+  while True:
+    try:
+      e = expected[i]
+      a = actual[j]
+      if e < a:
+        missing.append(e)
+        i += 1
+        while expected[i] == e:
+          i += 1
+      elif e > a:
+        unexpected.append(a)
+        j += 1
+        while actual[j] == a:
+          j += 1
+      else:
+        i += 1
+        try:
+          while expected[i] == e:
+            i += 1
+        finally:
+          j += 1
+          while actual[j] == a:
+            j += 1
+    except IndexError:
+      missing.extend(expected[i:])
+      unexpected.extend(actual[j:])
+      break
+  return missing, unexpected
+
+
+# ----------------------------------------------------------------------
+# Functions to compare the actual output of a test to the expected
+# (golden) output.
+#
+# Note: We could just replace the sys.stdout and sys.stderr objects,
+# but we actually redirect the underlying file objects so that if the
+# Python script execs any subprocess, their output will also be
+# redirected.
+#
+# Usage:
+#   basetest.CaptureTestStdout()
+#   ... do something ...
+#   basetest.DiffTestStdout("... path to golden file ...")
+# ----------------------------------------------------------------------
+
+
+class CapturedStream(object):
+  """A temporarily redirected output stream."""
+
+  def __init__(self, stream, filename):
+    self._stream = stream
+    self._fd = stream.fileno()
+    self._filename = filename
+
+    # Keep original stream for later
+    self._uncaptured_fd = os.dup(self._fd)
+
+    # Open file to save stream to
+    cap_fd = os.open(self._filename,
+                     os.O_CREAT | os.O_TRUNC | os.O_WRONLY,
+                     0600)
+
+    # Send stream to this file
+    self._stream.flush()
+    os.dup2(cap_fd, self._fd)
+    os.close(cap_fd)
+
+  def RestartCapture(self):
+    """Resume capturing output to a file (after calling StopCapture)."""
+    # Original stream fd
+    assert self._uncaptured_fd
+
+    # Append stream to file
+    cap_fd = os.open(self._filename,
+                     os.O_CREAT | os.O_APPEND | os.O_WRONLY,
+                     0600)
+
+    # Send stream to this file
+    self._stream.flush()
+    os.dup2(cap_fd, self._fd)
+    os.close(cap_fd)
+
+  def StopCapture(self):
+    """Remove output redirection."""
+    self._stream.flush()
+    os.dup2(self._uncaptured_fd, self._fd)
+
+  def filename(self):
+    return self._filename
+
+  def __del__(self):
+    self.StopCapture()
+    os.close(self._uncaptured_fd)
+    del self._uncaptured_fd
+
+
+_captured_streams = {}
+
+
+def _CaptureTestOutput(stream, filename):
+  """Redirect an output stream to a file.
+
+  Args:
+    stream: Should be sys.stdout or sys.stderr.
+    filename: File where output should be stored.
+  """
+  assert not _captured_streams.has_key(stream)
+  _captured_streams[stream] = CapturedStream(stream, filename)
+
+
+def _DiffTestOutput(stream, golden_filename):
+  """Compare ouput of redirected stream to contents of golden file.
+
+  Args:
+    stream: Should be sys.stdout or sys.stderr.
+    golden_filename: Absolute path to golden file.
+  """
+  assert _captured_streams.has_key(stream)
+  cap = _captured_streams[stream]
+
+  for cap_stream in _captured_streams.itervalues():
+    cap_stream.StopCapture()
+
+  try:
+    _Diff(cap.filename(), golden_filename)
+  finally:
+    # remove the current stream
+    del _captured_streams[stream]
+    # restore other stream capture
+    for cap_stream in _captured_streams.itervalues():
+      cap_stream.RestartCapture()
+
+
+# Public interface
+def CaptureTestStdout(outfile=None):
+  if not outfile:
+    outfile = os.path.join(FLAGS.test_tmpdir, 'captured.out')
+
+  _CaptureTestOutput(sys.stdout, outfile)
+
+
+def CaptureTestStderr(outfile=None):
+  if not outfile:
+    outfile = os.path.join(FLAGS.test_tmpdir, 'captured.err')
+
+  _CaptureTestOutput(sys.stderr, outfile)
+
+
+def DiffTestStdout(golden):
+  _DiffTestOutput(sys.stdout, golden)
+
+
+def DiffTestStderr(golden):
+  _DiffTestOutput(sys.stderr, golden)
+
+
+def StopCapturing():
+  while _captured_streams:
+    _, cap_stream = _captured_streams.popitem()
+    cap_stream.StopCapture()
+    del cap_stream
+
+
+def _WriteTestData(data, filename):
+  """Write data into file named filename."""
+  fd = os.open(filename, os.O_CREAT | os.O_TRUNC | os.O_WRONLY, 0600)
+  os.write(fd, data)
+  os.close(fd)
+
+
+class OutputDifferedError(AssertionError):
+  pass
+
+
+class DiffFailureError(Exception):
+  pass
+
+
+def _Diff(lhs, rhs):
+  """Run standard unix 'diff' against two files."""
+
+  cmd = '${TEST_DIFF:-diff} %s %s' % (commands.mkarg(lhs), commands.mkarg(rhs))
+  (status, output) = commands.getstatusoutput(cmd)
+  if os.WIFEXITED(status) and os.WEXITSTATUS(status) == 1:
+    # diff outputs must be the same as c++ and shell
+    raise OutputDifferedError('\nRunning %s\n%s\nTest output differed '
+                              'from golden file\n' % (cmd, output))
+  elif not os.WIFEXITED(status) or os.WEXITSTATUS(status) != 0:
+    raise DiffFailureError('\nRunning %s\n%s\nFailure diffing test output '
+                           'with golden file\n' % (cmd, output))
+
+
+def DiffTestStringFile(data, golden):
+  """Diff data agains a golden file."""
+  data_file = os.path.join(FLAGS.test_tmpdir, 'provided.dat')
+  _WriteTestData(data, data_file)
+  _Diff(data_file, golden)
+
+
+def DiffTestStrings(data1, data2):
+  """Diff two strings."""
+  data1_file = os.path.join(FLAGS.test_tmpdir, 'provided_1.dat')
+  _WriteTestData(data1, data1_file)
+  data2_file = os.path.join(FLAGS.test_tmpdir, 'provided_2.dat')
+  _WriteTestData(data2, data2_file)
+  _Diff(data1_file, data2_file)
+
+
+def DiffTestFiles(testgen, golden):
+  _Diff(testgen, golden)
+
+
+def GetCommandString(command):
+  """Returns an escaped string that can be used as a shell command.
+
+  Args:
+    command: List or string representing the command to run.
+  Returns:
+    A string suitable for use as a shell command.
+  """
+  if isinstance(command, types.StringTypes):
+    return command
+  else:
+    return shellutil.ShellEscapeList(command)
+
+
+def GetCommandStderr(command, env=None, close_fds=True):
+  """Runs the given shell command and returns a tuple.
+
+  Args:
+    command: List or string representing the command to run.
+    env: Dictionary of environment variable settings.
+    close_fds: Whether or not to close all open fd's in the child after forking.
+
+  Returns:
+    Tuple of (exit status, text printed to stdout and stderr by the command).
+  """
+  if env is None: env = {}
+  # Forge needs PYTHON_RUNFILES in order to find the runfiles directory when a
+  # Python executable is run by a Python test.  Pass this through from the
+  # parent environment if not explicitly defined.
+  if os.environ.get('PYTHON_RUNFILES') and not env.get('PYTHON_RUNFILES'):
+    env['PYTHON_RUNFILES'] = os.environ['PYTHON_RUNFILES']
+
+  use_shell = isinstance(command, types.StringTypes)
+  process = subprocess.Popen(
+      command,
+      close_fds=close_fds,
+      env=env,
+      shell=use_shell,
+      stderr=subprocess.STDOUT,
+      stdout=subprocess.PIPE)
+  output = process.communicate()[0]
+  exit_status = process.wait()
+  return (exit_status, output)
+
+
+def _QuoteLongString(s):
+  """Quotes a potentially multi-line string to make the start and end obvious.
+
+  Args:
+    s: A string.
+
+  Returns:
+    The quoted string.
+  """
+  return ('8<-----------\n' +
+          s + '\n' +
+          '----------->8\n')
+
+
+class TestProgramManualRun(unittest.TestProgram):
+  """A TestProgram which runs the tests manually."""
+
+  def runTests(self, do_run=False):
+    """Run the tests."""
+    if do_run:
+      unittest.TestProgram.runTests(self)
+
+
+def main(*args, **kwargs):
+  """Executes a set of Python unit tests.
+
+  Usually this function is called without arguments, so the
+  unittest.TestProgram instance will get created with the default settings,
+  so it will run all test methods of all TestCase classes in the __main__
+  module.
+
+  Args:
+    args: Positional arguments passed through to unittest.TestProgram.__init__.
+    kwargs: Keyword arguments passed through to unittest.TestProgram.__init__.
+  """
+  _RunInApp(RunTests, args, kwargs)
+
+
+def _IsInAppMain():
+  """Returns True iff app.main or app.really_start is active."""
+  f = sys._getframe().f_back
+  app_dict = app.__dict__
+  while f:
+    if f.f_globals is app_dict and f.f_code.co_name in ('run', 'really_start'):
+      return True
+    f = f.f_back
+  return False
+
+
+class SavedFlag(object):
+  """Helper class for saving and restoring a flag value."""
+
+  def __init__(self, flag):
+    self.flag = flag
+    self.value = flag.value
+    self.present = flag.present
+
+  def RestoreFlag(self):
+    self.flag.value = self.value
+    self.flag.present = self.present
+
+
+def _RunInApp(function, args, kwargs):
+  """Executes a set of Python unit tests, ensuring app.really_start.
+
+  Most users should call basetest.main() instead of _RunInApp.
+
+  _RunInApp calculates argv to be the command-line arguments of this program
+  (without the flags), sets the default of FLAGS.alsologtostderr to True,
+  then it calls function(argv, args, kwargs), making sure that `function'
+  will get called within app.run() or app.really_start(). _RunInApp does this
+  by checking whether it is called by either app.run() or
+  app.really_start(), or by calling app.really_start() explicitly.
+
+  The reason why app.really_start has to be ensured is to make sure that
+  flags are parsed and stripped properly, and other initializations done by
+  the app module are also carried out, no matter if basetest.run() is called
+  from within or outside app.run().
+
+  If _RunInApp is called from within app.run(), then it will reparse
+  sys.argv and pass the result without command-line flags into the argv
+  argument of `function'. The reason why this parsing is needed is that
+  __main__.main() calls basetest.main() without passing its argv. So the
+  only way _RunInApp could get to know the argv without the flags is that
+  it reparses sys.argv.
+
+  _RunInApp changes the default of FLAGS.alsologtostderr to True so that the
+  test program's stderr will contain all the log messages unless otherwise
+  specified on the command-line. This overrides any explicit assignment to
+  FLAGS.alsologtostderr by the test program prior to the call to _RunInApp()
+  (e.g. in __main__.main).
+
+  Please note that _RunInApp (and the function it calls) is allowed to make
+  changes to kwargs.
+
+  Args:
+    function: basetest.RunTests or a similar function. It will be called as
+      function(argv, args, kwargs) where argv is a list containing the
+      elements of sys.argv without the command-line flags.
+    args: Positional arguments passed through to unittest.TestProgram.__init__.
+    kwargs: Keyword arguments passed through to unittest.TestProgram.__init__.
+  """
+  if _IsInAppMain():
+    # Save command-line flags so the side effects of FLAGS(sys.argv) can be
+    # undone.
+    saved_flags = dict((f.name, SavedFlag(f))
+                       for f in FLAGS.FlagDict().itervalues())
+
+    # Here we'd like to change the default of alsologtostderr from False to
+    # True, so the test programs's stderr will contain all the log messages.
+    # The desired effect is that if --alsologtostderr is not specified in
+    # the command-line, and __main__.main doesn't set FLAGS.logtostderr
+    # before calling us (basetest.main), then our changed default takes
+    # effect and alsologtostderr becomes True.
+    #
+    # However, we cannot achive this exact effect, because here we cannot
+    # distinguish these situations:
+    #
+    # A. main.__main__ has changed it to False, it hasn't been specified on
+    #    the command-line, and the default was kept as False. We should keep
+    #    it as False.
+    #
+    # B. main.__main__ hasn't changed it, it hasn't been specified on the
+    #    command-line, and the default was kept as False. We should change
+    #    it to True here.
+    #
+    # As a workaround, we assume that main.__main__ never changes
+    # FLAGS.alsologstderr to False, thus the value of the flag is determined
+    # by its default unless the command-line overrides it. We want to change
+    # the default to True, and we do it by setting the flag value to True, and
+    # letting the command-line override it in FLAGS(sys.argv) below by not
+    # restoring it in saved_flag.RestoreFlag().
+    if 'alsologtostderr' in saved_flags:
+      FLAGS.alsologtostderr = True
+      del saved_flags['alsologtostderr']
+
+    # The call FLAGS(sys.argv) parses sys.argv, returns the arguments
+    # without the flags, and -- as a side effect -- modifies flag values in
+    # FLAGS. We don't want the side effect, because we don't want to
+    # override flag changes the program did (e.g. in __main__.main)
+    # after the command-line has been parsed. So we have the for loop below
+    # to change back flags to their old values.
+    argv = FLAGS(sys.argv)
+    for saved_flag in saved_flags.itervalues():
+      saved_flag.RestoreFlag()
+
+
+    function(argv, args, kwargs)
+  else:
+    # Send logging to stderr. Use --alsologtostderr instead of --logtostderr
+    # in case tests are reading their own logs.
+    if 'alsologtostderr' in FLAGS:
+      FLAGS.SetDefault('alsologtostderr', True)
+
+    def Main(argv):
+      function(argv, args, kwargs)
+
+    app.really_start(main=Main)
+
+
+def RunTests(argv, args, kwargs):
+  """Executes a set of Python unit tests within app.really_start.
+
+  Most users should call basetest.main() instead of RunTests.
+
+  Please note that RunTests should be called from app.really_start (which is
+  called from app.run()). Calling basetest.main() would ensure that.
+
+  Please note that RunTests is allowed to make changes to kwargs.
+
+  Args:
+    argv: sys.argv with the command-line flags removed from the front, i.e. the
+      argv with which app.run() has called __main__.main.
+    args: Positional arguments passed through to unittest.TestProgram.__init__.
+    kwargs: Keyword arguments passed through to unittest.TestProgram.__init__.
+  """
+  test_runner = kwargs.get('testRunner')
+
+  # Make sure tmpdir exists
+  if not os.path.isdir(FLAGS.test_tmpdir):
+    os.makedirs(FLAGS.test_tmpdir)
+
+  # Run main module setup, if it exists
+  main_mod = sys.modules['__main__']
+  if hasattr(main_mod, 'setUp') and callable(main_mod.setUp):
+    main_mod.setUp()
+
+  # Let unittest.TestProgram.__init__ called by
+  # TestProgramManualRun.__init__ do its own argv parsing, e.g. for '-v',
+  # on argv, which is sys.argv without the command-line flags.
+  kwargs.setdefault('argv', argv)
+
+  try:
+    result = None
+    test_program = TestProgramManualRun(*args, **kwargs)
+    if test_runner:
+      test_program.testRunner = test_runner
+    else:
+      test_program.testRunner = unittest.TextTestRunner(
+          verbosity=test_program.verbosity)
+    result = test_program.testRunner.run(test_program.test)
+  finally:
+    # Run main module teardown, if it exists
+    if hasattr(main_mod, 'tearDown') and callable(main_mod.tearDown):
+      main_mod.tearDown()
+
+  sys.exit(not result.wasSuccessful())