def testOneCfg(self, oVM, oTestVm):
        """
        Runs the specified VM thru the tests.

        Returns a success indicator on the general test execution. This is not
        the actual test result.
        """
        fRc = False;

        sXmlFile = self.prepareResultFile();
        asEnv = [ 'IPRT_TEST_FILE=' + sXmlFile];

        self.logVmInfo(oVM);
        oSession = self.startVm(oVM, sName = oTestVm.sVmName, asEnv = asEnv);
        if oSession is not None:
            self.addTask(oSession);

            cMsTimeout = 15*60*1000;
            if not reporter.isLocal(): ## @todo need to figure a better way of handling timeouts on the testboxes ...
                cMsTimeout = self.adjustTimeoutMs(180 * 60000);

            oRc = self.waitForTasks(cMsTimeout);
            self.removeTask(oSession);
            if oRc == oSession:
                fRc = oSession.assertPoweredOff();
            else:
                reporter.error('oRc=%s, expected %s' % (oRc, oSession));

            reporter.addSubXmlFile(sXmlFile);
            self.terminateVmBySession(oSession);
        return fRc;

 def actionVerify(self):
     if self.sVBoxValidationKitIso is None or not os.path.isfile(self.sVBoxValidationKitIso):
         reporter.error('Cannot find the VBoxValidationKit.iso! (%s)'
                        'Please unzip a Validation Kit build in the current directory or in some parent one.'
                        % (self.sVBoxValidationKitIso,) );
         return False;
     return vbox.TestDriver.actionVerify(self);

    def testOneVmConfig(self, oVM, oTestVm):
        """
        Install guest OS and wait for result
        """

        self.logVmInfo(oVM)
        reporter.testStart('Installing %s' % (oTestVm.sVmName,))

        cMsTimeout = 40*60000;
        if not reporter.isLocal(): ## @todo need to figure a better way of handling timeouts on the testboxes ...
            cMsTimeout = 180 * 60000; # will be adjusted down.

        oSession, _ = self.startVmAndConnectToTxsViaTcp(oTestVm.sVmName, fCdWait = False, cMsTimeout = cMsTimeout);
        if oSession is not None:
            # The guest has connected to TXS, so we're done (for now anyways).
            reporter.log('Guest reported success')
            ## @todo Do save + restore.

            reporter.testDone()
            fRc = self.terminateVmBySession(oSession)
            return fRc is True

        reporter.error('Installation of %s has failed' % (oTestVm.sVmName,))
        oTestVm.detatchAndDeleteHd(self); # Save space.
        reporter.testDone()
        return False

    def _getVBoxInstallPath(self, fFailIfNotFound):
        """ Returns the default VBox installation path. """
        sHost = utils.getHostOs();
        if sHost == 'win':
            sProgFiles = os.environ.get('ProgramFiles', 'C:\\Program Files');
            asLocs = [
                os.path.join(sProgFiles, 'Oracle', 'VirtualBox'),
                os.path.join(sProgFiles, 'OracleVM', 'VirtualBox'),
                os.path.join(sProgFiles, 'Sun', 'VirtualBox'),
            ];
        elif sHost == 'linux' or sHost == 'solaris':
            asLocs = [ '/opt/VirtualBox', '/opt/VirtualBox-3.2', '/opt/VirtualBox-3.1', '/opt/VirtualBox-3.0'];
        elif sHost == 'darwin':
            asLocs = [ '/Applications/VirtualBox.app/Contents/MacOS' ];
        else:
            asLocs = [ '/opt/VirtualBox' ];
        if 'VBOX_INSTALL_PATH' in os.environ:
            asLocs.insert(0, os.environ.get('VBOX_INSTALL_PATH', None));

        for sLoc in asLocs:
            if os.path.isdir(sLoc):
                return sLoc;
        if fFailIfNotFound:
            reporter.error('Failed to locate VirtualBox installation: %s' % (asLocs,));
        else:
            reporter.log2('Failed to locate VirtualBox installation: %s' % (asLocs,));
        return None;

 def testEventQueueWaitingThreadProc(self):
     """ Thread procedure for checking that waitForEvents fails when not called by the main thread. """
     try:
         rc2 = self.oVBoxMgr.waitForEvents(0);
     except:
         return True;
     reporter.error('waitForEvents() returned "%s" when called on a worker thread, expected exception.' % (rc2,));
     return False;

    def _installVBox(self):
        """
        Download / copy the build files into the scratch area and install them.
        """
        reporter.testStart('Installing VirtualBox');
        reporter.log('CWD=%s' % (os.getcwd(),)); # curious

        #
        # Download the build files.
        #
        for i in range(len(self._asBuildUrls)):
            if webutils.downloadFile(self._asBuildUrls[i], self._asBuildFiles[i],
                                     self.sBuildPath, reporter.log, reporter.log) is not True:
                reporter.testDone(fSkipped = True);
                return None; # Failed to get binaries, probably deleted. Skip the test run.

        #
        # Unpack anything we know what is and append it to the build files
        # list.  This allows us to use VBoxAll*.tar.gz files.
        #
        for sFile in list(self._asBuildFiles):
            if self._maybeUnpackArchive(sFile, fNonFatal = True) is not True:
                reporter.testDone(fSkipped = True);
                return None; # Failed to unpack. Probably local error, like busy
                             # DLLs on windows, no reason for failing the build.

        #
        # Go to system specific installation code.
        #
        sHost = utils.getHostOs()
        if   sHost == 'darwin':     fRc = self._installVBoxOnDarwin();
        elif sHost == 'linux':      fRc = self._installVBoxOnLinux();
        elif sHost == 'solaris':    fRc = self._installVBoxOnSolaris();
        elif sHost == 'win':        fRc = self._installVBoxOnWindows();
        else:
            reporter.error('Unsupported host "%s".' % (sHost,));
        if fRc is False:
            reporter.testFailure('Installation error.');
        elif fRc is not True:
            reporter.log('Seems installation was skipped. Old version lurking behind? Not the fault of this build/test run!');

        #
        # Install the extension pack.
        #
        if fRc is True  and  self._fAutoInstallPuelExtPack:
            fRc = self._installExtPack();
            if fRc is False:
                reporter.testFailure('Extension pack installation error.');

        # Some debugging...
        try:
            cMbFreeSpace = utils.getDiskUsage(self.sScratchPath);
            reporter.log('Disk usage after VBox install: %d MB available at %s' % (cMbFreeSpace, self.sScratchPath,));
        except:
            reporter.logXcpt('Unable to get disk free space. Ignored. Continuing.');

        reporter.testDone(fRc is None);
        return fRc;

 def interruptWaitEventsThreadProc(self):
     """ Thread procedure that's used for waking up the main thread. """
     time.sleep(2);
     try:
         rc2 = self.oVBoxMgr.interruptWaitEvents();
     except:
         reporter.errorXcpt();
     else:
         if rc2 is True:
             return True;
         reporter.error('interruptWaitEvents returned "%s" when called from other thread, expected True' % (rc2,));
     return False;

    def _isExcluded(self, sTest, dExclList):
        """ Checks if the testcase is excluded or not. """
        if sTest in dExclList:
            sFullExpr = dExclList[sTest].replace(" ", "").strip()
            if sFullExpr == "":
                return True

            # Consider each exclusion expression. These are generally ranges,
            # either open ended or closed: "<4.3.51r12345", ">=4.3.0 && <=4.3.4".
            asExprs = sFullExpr.split(";")
            for sExpr in asExprs:

                # Split it on the and operator and process each sub expression.
                fResult = True
                for sSubExpr in sExpr.split("&&"):
                    # Split out the comparison operator and the version value.
                    if sSubExpr.startswith("<=") or sSubExpr.startswith(">="):
                        sOp = sSubExpr[:2]
                        sValue = sSubExpr[2:]
                    elif sSubExpr.startswith("<") or sSubExpr.startswith(">") or sSubExpr.startswith("="):
                        sOp = sSubExpr[:1]
                        sValue = sSubExpr[1:]
                    else:
                        sOp = sValue = ""

                    # Convert the version value, making sure we've got a valid one.
                    try:
                        aiValue = [int(sComp) for sComp in sValue.replace("r", ".").split(".")]
                    except:
                        aiValue = ()
                    if len(aiValue) == 0 or len(aiValue) > 4:
                        reporter.error(
                            'Invalid exclusion expression for %s: "%s" [%s]' % (sTest, sSubExpr, dExclList[sTest])
                        )
                        return True

                    # Do the compare.
                    iCmp = self._compareVersion(aiValue)
                    if sOp == ">=" and iCmp < 0:
                        fResult = False
                    elif sOp == ">" and iCmp <= 0:
                        fResult = False
                    elif sOp == "<" and iCmp >= 0:
                        fResult = False
                    elif sOp == ">=" and iCmp < 0:
                        fResult = False
                    reporter.log2("iCmp=%s; %s %s %s -> %s" % (iCmp, self.aiVBoxVer, sOp, aiValue, fResult))

                # Did the expression match?
                if fResult:
                    return True

        return False

    def _isExcluded(self, sTest, dExclList):
        """ Checks if the testcase is excluded or not. """
        if sTest in dExclList:
            sFullExpr = dExclList[sTest].replace(' ', '').strip();
            if sFullExpr == '':
                return True;

            # Consider each exclusion expression. These are generally ranges,
            # either open ended or closed: "<4.3.51r12345", ">=4.3.0 && <=4.3.4".
            asExprs = sFullExpr.split(';');
            for sExpr in asExprs:

                # Split it on the and operator and process each sub expression.
                fResult = True;
                for sSubExpr in sExpr.split('&&'):
                    # Split out the comparison operator and the version value.
                    if sSubExpr.startswith('<=') or sSubExpr.startswith('>='):
                        sOp = sSubExpr[:2];
                        sValue = sSubExpr[2:];
                    elif sSubExpr.startswith('<') or sSubExpr.startswith('>') or sSubExpr.startswith('='):
                        sOp = sSubExpr[:1];
                        sValue = sSubExpr[1:];
                    else:
                        sOp = sValue = '';

                    # Convert the version value, making sure we've got a valid one.
                    try:    aiValue = [int(sComp) for sComp in sValue.replace('r', '.').split('.')];
                    except: aiValue = ();
                    if len(aiValue) == 0 or len(aiValue) > 4:
                        reporter.error('Invalid exclusion expression for %s: "%s" [%s]' % (sTest, sSubExpr, dExclList[sTest]));
                        return True;

                    # Do the compare.
                    iCmp = self._compareVersion(aiValue);
                    if sOp == '>=' and iCmp < 0:
                        fResult = False;
                    elif sOp == '>' and iCmp <= 0:
                        fResult = False;
                    elif sOp == '<' and iCmp >= 0:
                        fResult = False;
                    elif sOp == '>=' and iCmp < 0:
                        fResult = False;
                    reporter.log2('iCmp=%s; %s %s %s -> %s' % (iCmp, self.aiVBoxVer, sOp, aiValue, fResult));

                # Did the expression match?
                if fResult:
                    return True;

        return False;

    def _findFile(self, sRegExp, sTestBuildDir):
        """
        Returns a filepath based on the given regex and path to look into
        or None if no matching file is found.
        """

        oRegExp = re.compile(sRegExp);

        asFiles = os.listdir(sTestBuildDir);

        for sFile in asFiles:
            if oRegExp.match(os.path.basename(sFile)) and os.path.exists(sTestBuildDir + '/' + sFile):
                return sTestBuildDir + '/' + sFile;

        reporter.error('Failed to find a file matching "%s" in %s.' % (sRegExp, sTestBuildDir));
        return None;

    def _findFile(self, sRegExp, fMandatory = False):
        """
        Returns the first build file that matches the given regular expression
        (basename only).

        Returns None if no match was found, logging it as an error if
        fMandatory is set.
        """
        oRegExp = re.compile(sRegExp);

        for sFile in self._asBuildFiles:
            if oRegExp.match(os.path.basename(sFile)) and os.path.exists(sFile):
                return sFile;

        if fMandatory:
            reporter.error('Failed to find a file matching "%s" in %s.' % (sRegExp, self._asBuildFiles,));
        return None;

    def testInstallAdditions(self, oSession, oTxsSession, oTestVm):
        """
        Tests installing the guest additions
        """
        if oTestVm.isWindows():
            (fRc, oTxsSession) = self.testWindowsInstallAdditions(oSession, oTxsSession, oTestVm)
        else:
            reporter.error(
                "Guest Additions installation not implemented for %s yet! (%s)" % (oTestVm.sKind, oTestVm.sVmName)
            )
            fRc = False

        #
        # Verify installation of Guest Additions using commmon bits.
        #
        if fRc is True:
            #
            # Wait for the GAs to come up.
            #

            ## @todo need to signed up for a OnAdditionsStateChanged and wait runlevel to
            #  at least reach Userland.

            #
            # Check if the additions are operational.
            #
            try:
                oGuest = oSession.o.console.guest
            except:
                reporter.errorXcpt("Getting IGuest failed.")
                return (False, oTxsSession)

            # Check the additionsVersion attribute. It must not be empty.
            reporter.testStart("IGuest::additionsVersion")
            fRc = self.testIGuest_additionsVersion(oGuest)
            reporter.testDone()

            reporter.testStart("IGuest::additionsRunLevel")
            self.testIGuest_additionsRunLevel(oGuest, oTestVm)
            reporter.testDone()

            ## @todo test IAdditionsFacilities.

        return (fRc, oTxsSession)

    def completeOptions(self):
        #
        # Check that we've got what we need.
        #
        if len(self._asBuildUrls) == 0:
            reporter.error('No build files specfiied ("--vbox-build file1[,file2[...]]")');
            return False;
        if len(self._asSubDriver) == 0:
            reporter.error('No sub testdriver specified. (" -- test/stuff/tdStuff1.py args")');
            return False;

        #
        # Construct _asBuildFiles as an array parallel to _asBuildUrls.
        #
        for sUrl in self._asBuildUrls:
            sDstFile = os.path.join(self.sScratchPath, webutils.getFilename(sUrl));
            self._asBuildFiles.append(sDstFile);

        return TestDriverBase.completeOptions(self);

    def testDoInstallGuestOs(self):
        """
        Install guest OS and wait for result
        """
        reporter.testStart('Installing %s' % (os.path.basename(self.sIso),))

        cMsTimeout = 40*60000;
        if not reporter.isLocal(): ## @todo need to figure a better way of handling timeouts on the testboxes ...
            cMsTimeout = 180 * 60000; # will be adjusted down.

        oSession, _ = self.startVmAndConnectToTxsViaTcp(self.sVmName, fCdWait = False, cMsTimeout = cMsTimeout)
        if oSession is not None:
            # Wait until guest reported success
            reporter.log('Guest reported success')
            reporter.testDone()
            fRc = self.terminateVmBySession(oSession)
            return fRc is True
        reporter.error('Installation of %s has failed' % (self.sIso,))
        reporter.testDone()
        return False

    def testIGuest_additionsRunLevel(self, oGuest, oTestVm):
        """
        Do run level tests.
        """
        if oTestVm.isLoggedOntoDesktop():
            eExpectedRunLevel = vboxcon.AdditionsRunLevelType_Desktop;
        else:
            eExpectedRunLevel = vboxcon.AdditionsRunLevelType_Userland;

        ## @todo Insert wait for the desired run level.
        try:
            iLevel = oGuest.additionsRunLevel;
        except:
            reporter.errorXcpt('Getting the additions run level failed.');
            return False;
        reporter.log('IGuest::additionsRunLevel=%s' % (iLevel,));

        if iLevel != eExpectedRunLevel:
            reporter.error('Expected runlevel %d, found %d instead' % (eExpectedRunLevel, iLevel));
        return True;

    def _darwinUnmountDmg(self, fIgnoreError):
        """
        Umount any DMG on at the default mount point.
        """
        sMountPath = self._darwinDmgPath();
        if not os.path.exists(sMountPath):
            return True;

        # Unmount.
        fRc = self._executeSync(['hdiutil', 'detach', sMountPath ]);
        if not fRc and not fIgnoreError:
            reporter.error('Failed to unmount DMG at %s' % sMountPath);

        # Remove dir.
        try:
            os.rmdir(sMountPath);
        except:
            if not fIgnoreError:
                reporter.errorXcpt('Failed to remove directory %s' % sMountPath);
        return fRc;

    def testIGuest_additionsVersion(self, oGuest):
        """
        Returns False if no version string could be obtained, otherwise True
        even though errors are logged.
        """
        try:
            sVer = oGuest.additionsVersion
        except:
            reporter.errorXcpt("Getting the additions version failed.")
            return False
        reporter.log('IGuest::additionsVersion="%s"' % (sVer,))

        if sVer.strip() == "":
            reporter.error("IGuest::additionsVersion is empty.")
            return False

        if sVer != sVer.strip():
            reporter.error('IGuest::additionsVersion is contains spaces: "%s".' % (sVer,))

        asBits = sVer.split(".")
        if len(asBits) < 3:
            reporter.error(
                'IGuest::additionsVersion does not contain at least tree dot separated fields: "%s" (%d).'
                % (sVer, len(asBits))
            )

        ## @todo verify the format.
        return True

 def actionExecute(self):
     # Too many immediate sub-tests.
     if self.sOptWhich == 'immediate-sub-tests':
         reporter.testStart('Too many immediate sub-tests (negative)');
         for i in range(1024):
             reporter.testStart('subsub%d' % i);
             reporter.testDone();
     # Too many sub-tests in total.
     elif self.sOptWhich == 'total-sub-tests':
         reporter.testStart('Too many sub-tests (negative)');
         # 32 * 256 = 2^(5+8) = 2^13 = 8192.
         for i in range(32):
             reporter.testStart('subsub%d' % i);
             for j in range(256):
                 reporter.testStart('subsubsub%d' % j);
                 reporter.testDone();
             reporter.testDone();
     # Too many immediate values.
     elif self.sOptWhich == 'immediate-values':
         reporter.testStart('Too many immediate values (negative)');
         for i in range(512):
             reporter.testValue('value%d' % i, i, 'times');
     # Too many values in total.
     elif self.sOptWhich == 'total-values':
         reporter.testStart('Too many sub-tests (negative)');
         for i in range(256):
             reporter.testStart('subsub%d' % i);
             for j in range(64):
                 reporter.testValue('value%d' % j, i * 10000 + j, 'times');
             reporter.testDone();
     # Too many failure reasons (only immediate since the limit is extremely low).
     elif self.sOptWhich == 'immediate-messages':
         reporter.testStart('Too many immediate messages (negative)');
         for i in range(16):
             reporter.testFailure('Detail %d' % i);
     else:
         reporter.testStart('Unknown test %s' % (self.sOptWhich,));
         reporter.error('Invalid test selected: %s' % (self.sOptWhich,));
     reporter.testDone();
     return True;

    def _uninstallVBox(self, fIgnoreError = False):
        """
        Uninstall VirtualBox.
        """
        reporter.testStart('Uninstalling VirtualBox');

        sHost = utils.getHostOs()
        if   sHost == 'darwin':     fRc = self._uninstallVBoxOnDarwin();
        elif sHost == 'linux':      fRc = self._uninstallVBoxOnLinux();
        elif sHost == 'solaris':    fRc = self._uninstallVBoxOnSolaris();
        elif sHost == 'win':        fRc = self._uninstallVBoxOnWindows();
        else:
            reporter.error('Unsupported host "%s".' % (sHost,));
        if fRc is False and not fIgnoreError:
            reporter.testFailure('Uninstallation failed.');

        fRc2 = self._uninstallAllExtPacks();
        if not fRc2 and fRc:
            fRc = fRc2;

        reporter.testDone(fSkipped = (fRc is None));
        return fRc;

    def testEventQueueWaiting(self):
        """
        Test event queue waiting.
        """
        reporter.testStart('waitForEvents');

        # Check return values and such.
        for cMsTimeout in (0, 1, 2, 3, 256, 1000, 0):
            iLoop = 0;
            while True:
                try:
                    rc = self.oVBoxMgr.waitForEvents(cMsTimeout);
                except:
                    reporter.errorXcpt();
                    break;
                if not isinstance(rc, types.IntType):
                    reporter.error('waitForEvents returns non-integer type');
                    break;
                if rc == 1:
                    break;
                if rc != 0:
                    reporter.error('waitForEvents returns "%s", expected 0 or 1' % (rc,));
                    break;
                iLoop += 1;
                if iLoop > 10240:
                    reporter.error('waitForEvents returns 0 (success) %u times. '
                                   'Expected 1 (timeout/interrupt) after a call or two.'
                                   % (iLoop,));
                    break;
            if reporter.testErrorCount() != 0:
                break;

        # Check that we get an exception when trying to call the method from
        # a different thread.
        reporter.log('If running a debug build, you will see an ignored assertion now. Please ignore it.')
        sVBoxAssertSaved = os.environ.get('VBOX_ASSERT', 'breakpoint');
        os.environ['VBOX_ASSERT'] = 'ignore';
        oThread = threading.Thread(target=self.testEventQueueWaitingThreadProc);
        oThread.start();
        oThread.join();
        os.environ['VBOX_ASSERT'] = sVBoxAssertSaved;

        return reporter.testDone()[1] == 0;