def testSnapshotTreeDepth(self):
        """
        Test snapshot tree depth.
        """
        reporter.testStart('snapshotTreeDepth')

        try:
            oVM = self.createTestVM('test-snap', 1, None, 4)
            assert oVM is not None

            # modify the VM config, create and attach empty HDD
            oSession = self.openSession(oVM)
            sHddPath = os.path.join(self.sScratchPath, 'TestSnapEmpty.vdi')
            fRc = True
            fRc = fRc and oSession.createAndAttachHd(sHddPath, cb=1024*1024, sController='SATA Controller', fImmutable=False)
            fRc = fRc and oSession.saveSettings()

            # take 250 snapshots (snapshot tree depth limit)
            for i in range(1, 251):
                fRc = fRc and oSession.takeSnapshot('Snapshot ' + str(i))
            fRc = oSession.close() and fRc

            # unregister and re-register to test loading of settings
            sSettingsFile = oVM.settingsFilePath
            reporter.log('unregistering VM')
            oVM.unregister(vboxcon.CleanupMode_DetachAllReturnNone)
            oVBox = self.oVBoxMgr.getVirtualBox()
            reporter.log('opening VM %s, testing config reading' % (sSettingsFile))
            oVM = oVBox.openMachine(sSettingsFile)

            assert fRc is True
        except:
            reporter.errorXcpt()

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

    def moveTo(self, sLocation, aoMediumAttachments):
        for oAttachment in aoMediumAttachments:
            try:
                oMedium = oAttachment.medium
                reporter.log('Move medium "%s" to "%s"' % (oMedium.name, sLocation,))
            except:
                reporter.errorXcpt('failed to get the medium from the IMediumAttachment "%s"' % (oAttachment))

            if self.oTstDrv.fpApiVer >= 5.3 and self.oTstDrv.uRevision > 124748:
                try:
                    oProgress = vboxwrappers.ProgressWrapper(oMedium.moveTo(sLocation), self.oTstDrv.oVBoxMgr, self.oTstDrv,
                                                             'move "%s"' % (oMedium.name,));
                except:
                    return reporter.errorXcpt('Medium::moveTo("%s") for medium "%s" failed' % (sLocation, oMedium.name,));
            else:
                try:
                    oProgress = vboxwrappers.ProgressWrapper(oMedium.setLocation(sLocation), self.oTstDrv.oVBoxMgr, self.oTstDrv,
                                                             'move "%s"' % (oMedium.name,));
                except:
                    return reporter.errorXcpt('Medium::setLocation("%s") for medium "%s" failed' % (sLocation, oMedium.name,));


            oProgress.wait()
            if oProgress.logResult() is False:
                return False
        return True

    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 _sudoExecuteSync(self, asArgs, sInput):
        """
        Executes a sudo child process synchronously.
        Returns a tuple [True, 0] if the process executed successfully
        and returned 0, otherwise [False, rc] is returned.
        """
        reporter.log('Executing [sudo]: %s' % (asArgs, ));
        reporter.flushall();
        fRc = True;
        sOutput = '';
        sError = '';
        try:
            oProcess = utils.sudoProcessPopen(asArgs, stdout=subprocess.PIPE, stdin=subprocess.PIPE,
                                              stderr=subprocess.PIPE, shell = False, close_fds = False);

            sOutput, sError = oProcess.communicate(sInput);
            iExitCode  = oProcess.poll();

            if iExitCode is not 0:
                fRc = False;
        except:
            reporter.errorXcpt();
            fRc = False;
        reporter.log('Exit code [sudo]: %s (%s)' % (fRc, asArgs));
        return (fRc, str(sOutput), str(sError));

    def testRunUnitTestsSet(self, sTestCasePattern, sTestCaseSubDir):
        """
        Run subset of the unit tests set.
        """

        # Open /dev/null for use as stdin further down.
        try:
            oDevNull = open(os.path.devnull, 'w+');
        except:
            oDevNull = None;

        # Determin the host OS specific exclusion lists.
        dTestCasesBuggyForHostOs = self.kdTestCasesBuggyPerOs.get(utils.getHostOs(), []);
        dTestCasesBuggyForHostOs.update(self.kdTestCasesBuggyPerOs.get(utils.getHostOsDotArch(), []));

        #
        # Process the file list and run everything looking like a testcase.
        #
        for sFilename in sorted(os.listdir(os.path.join(self.sUnitTestsPathBase, sTestCaseSubDir))):
            # Separate base and suffix and morph the base into something we
            # can use for reporting and array lookups.
            sName, sSuffix = os.path.splitext(sFilename);
            if sTestCaseSubDir != '.':
                sName = sTestCaseSubDir + '/' + sName;

            # Basic exclusion.
            if   not re.match(sTestCasePattern, sFilename) \
              or sSuffix in self.kasSuffixBlackList:
                reporter.log('"%s" is not a test case.' % (sFilename,))
                continue

            # Check if the testcase is black listed or buggy before executing it.
            if self._isExcluded(sName, self.kdTestCasesBlackList):
                # (No testStart/Done or accounting here!)
                reporter.log('%s: SKIPPED (blacklisted)' % (sName,));

            elif self._isExcluded(sName, self.kdTestCasesBuggy):
                reporter.testStart(sName);
                reporter.log('%s: Skipping, buggy in general.' % (sName,));
                reporter.testDone(fSkipped = True);
                self.cSkipped += 1;

            elif self._isExcluded(sName, dTestCasesBuggyForHostOs):
                reporter.testStart(sName);
                reporter.log('%s: Skipping, buggy on %s.' % (sName, utils.getHostOs(),));
                reporter.testDone(fSkipped = True);
                self.cSkipped += 1;

            else:
                sFullPath = os.path.normpath(os.path.join(self.sUnitTestsPathBase, os.path.join(sTestCaseSubDir, sFilename)));
                reporter.testStart(sName);
                try:
                    fSkipped = self._executeTestCase(sName, sFullPath, sTestCaseSubDir, oDevNull);
                except:
                    reporter.errorXcpt('!*!');
                    self.cFailed += 1;
                    fSkipped = False;
                reporter.testDone(fSkipped);

 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 testImportOvaAsOvf(self, sOva):
        """
        Unpacks the OVA into a subdirectory in the scratch area and imports it as an OVF.
        """
        oVirtualBox = self.oTstDrv.oVBoxMgr.getVirtualBox();

        sTmpDir = os.path.join(self.oTstDrv.sScratchPath, os.path.split(sOva)[1] + '-ovf');
        sOvf    = os.path.join(sTmpDir, os.path.splitext(os.path.split(sOva)[1])[0] + '.ovf');

        #
        # Unpack
        #
        try:
            os.mkdir(sTmpDir, 0o755);
            oTarFile = tarfile.open(sOva, 'r:*');
            oTarFile.extractall(sTmpDir);
            oTarFile.close();
        except:
            return reporter.errorXcpt('Unpacking "%s" to "%s" for OVF style importing failed' % (sOvf, sTmpDir,));

        #
        # Import.
        #
        try:
            oAppliance2 = oVirtualBox.createAppliance();
        except:
            return reporter.errorXcpt('IVirtualBox::createAppliance failed (#2)');

        try:
            oProgress = vboxwrappers.ProgressWrapper(oAppliance2.read(sOvf), self.oTstDrv.oVBoxMgr, self.oTstDrv,
                                                     'read "%s"' % (sOvf,));
        except:
            return reporter.errorXcpt('IAppliance::read("%s") failed' % (sOvf,));
        oProgress.wait();
        if oProgress.logResult() is False:
            return False;

        try:
            oAppliance2.interpret();
        except:
            return reporter.errorXcpt('IAppliance::interpret() failed on "%s"' % (sOvf,));

        try:
            oProgress = vboxwrappers.ProgressWrapper(oAppliance2.importMachines([]),
                                                     self.oTstDrv.oVBoxMgr, self.oTstDrv, 'importMachines "%s"' % (sOvf,));
        except:
            return reporter.errorXcpt('IAppliance::importMachines failed on "%s"' % (sOvf,));
        oProgress.wait();
        if oProgress.logResult() is False:
            return False;

        return True;

 def _sudoExecuteSync(self, asArgs):
     """
     Executes a sudo child process synchronously.
     Returns True if the process executed successfully and returned 0,
     otherwise False is returned.
     """
     reporter.log('Executing [sudo]: %s' % (asArgs, ));
     try:
         iRc = utils.sudoProcessCall(asArgs, shell = False, close_fds = False);
     except:
         reporter.errorXcpt();
         return False;
     reporter.log('Exit code [sudo]: %s (%s)' % (iRc, asArgs));
     return iRc is 0;

    def cloneMedium(self, oSrcHd, oTgtHd):
        """
        Clones medium into target medium.
        """
        try:
            oProgressCom = oSrcHd.cloneTo(oTgtHd, (vboxcon.MediumVariant_Standard, ), None);
            oProgress = vboxwrappers.ProgressWrapper(oProgressCom, self.oVBoxMgr, self.oVBox.oTstDrv,
                                                     'clone base disk %s to %s' % (oSrcHd.name, oTgtHd.name));
            oProgress.wait(cMsTimeout = 60 * 1000);
            oProgress.logResult();
        except:
            reporter.errorXcpt('failed to clone medium %s to %s' % (oSrcHd.name, oTgtHd.name));
            return False;

        return True;

 def _sudoExecuteSync(self, asArgs):
     """
     Executes a sudo child process synchronously.
     Returns a tuple [True, 0] if the process executed successfully
     and returned 0, otherwise [False, rc] is returned.
     """
     reporter.log('Executing [sudo]: %s' % (asArgs, ));
     reporter.flushall();
     iRc = 0;
     try:
         iRc = utils.sudoProcessCall(asArgs, shell = False, close_fds = False);
     except:
         reporter.errorXcpt();
         return (False, 0);
     reporter.log('Exit code [sudo]: %s (%s)' % (iRc, asArgs));
     return (iRc is 0, iRc);

    def moveVMToLocation(self, sLocation, oVM):
        """
        Document me here, not with hashes above.
        """
        fRc = True
        try:

            ## @todo r=bird: Too much unncessary crap inside try clause.  Only oVM.moveTo needs to be here.
            ##               Though, you could make an argument for oVM.name too, perhaps.

            # move machine
            reporter.log('Moving machine "%s" to the "%s"' % (oVM.name, sLocation))
            sType = 'basic'
            oProgress = vboxwrappers.ProgressWrapper(oVM.moveTo(sLocation, sType), self.oTstDrv.oVBoxMgr, self.oTstDrv,
                                                     'moving machine "%s"' % (oVM.name,))

        except:
            return reporter.errorXcpt('Machine::moveTo("%s") for machine "%s" failed' % (sLocation, oVM.name,))

        oProgress.wait()
        if oProgress.logResult() is False:
            fRc = False
            reporter.log('Progress object returned False')
        else:
            fRc = True

        return fRc

    def _persistentVarUnset(self, sVar):
        """
        Unsets a persistent variable.

        Returns True on success, False + reporter.error on failure.

        May raise exception if the variable name is invalid or something
        unexpected happens.
        """
        sFull = self.__persistentVarCalcName(sVar);
        if os.path.exists(sFull):
            try:
                os.unlink(sFull);
            except:
                reporter.errorXcpt('Error unlinking "%s"' % (sFull,));
                return False;
        return True;

    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 _executeSync(self, asArgs, fMaySkip = False):
        """
        Executes a child process synchronously.

        Returns True if the process executed successfully and returned 0.
        Returns None if fMaySkip is true and the child exits with RTEXITCODE_SKIPPED.
        Returns False for all other cases.
        """
        reporter.log('Executing: %s' % (asArgs, ));
        reporter.flushall();
        try:
            iRc = utils.processCall(asArgs, shell = False, close_fds = False);
        except:
            reporter.errorXcpt();
            return False;
        reporter.log('Exit code: %s (%s)' % (iRc, asArgs));
        if fMaySkip and iRc == rtexitcode.RTEXITCODE_SKIPPED:
            return None;
        return iRc is 0;

    def testIt(self):
        """
        Execute the sub-testcase.
        """
        fRc = True;

        # Import a set of simple OVAs.
        # Note! Manifests generated by ovftool 4.0.0 does not include the ovf, while the ones b 4.1.0 does.
        for sOva in (
            # t1 is a plain VM without any disks, ovftool 4.0 export from fusion
            'tdAppliance1-t1.ova',
            # t2 is a plain VM with one disk. Both 4.0 and 4.1.0 exports.
            'tdAppliance1-t2.ova',
            'tdAppliance1-t2-ovftool-4.1.0.ova',
            # t3 is a VM with one gzipped disk and selecting SHA256 on the ovftool cmdline (--compress=9 --shaAlgorithm=sha256).
            'tdAppliance1-t3.ova',
            'tdAppliance1-t3-ovftool-4.1.0.ova',
            # t4 is a VM with with two gzipped disk, SHA256 and a (self) signed manifest (--privateKey=./tdAppliance1-t4.pem).
            'tdAppliance1-t4.ova',
            'tdAppliance1-t4-ovftool-4.1.0.ova',
            # t5 is a VM with with one gzipped disk, SHA1 and a manifest signed by a valid (2016) DigiCert code signing cert.
            'tdAppliance1-t5.ova',
            'tdAppliance1-t5-ovftool-4.1.0.ova',
            # t6 is a VM with with one gzipped disk, SHA1 and a manifest signed by a certificate issued by the t4 certificate,
            # thus it should be impossible to establish a trusted path to a root CA.
            'tdAppliance1-t6.ova',
            'tdAppliance1-t6-ovftool-4.1.0.ova',
            # t7 is based on tdAppliance1-t2-ovftool-4.1.0.ova and has modified to have an invalid InstanceID as well as an
            # extra readme file.  It was tarred up using bsdtar 2.4.12 on windows, so it uses a slightly different tar format and
            # have different file attributes.
            'tdAppliance1-t7-bad-instance.ova',
            ):
            reporter.testStart(sOva);
            try:
                fRc = self.testImportOva(os.path.join(g_ksValidationKitDir, 'tests', 'api', sOva)) and fRc;
                fRc = self.testImportOvaAsOvf(os.path.join(g_ksValidationKitDir, 'tests', 'api', sOva)) and fRc;
            except:
                reporter.errorXcpt();
                fRc = False;
            fRc = reporter.testDone() and fRc;

        ## @todo more stuff
        return fRc;

    def _persistentVarSet(self, sVar, sValue = ''):
        """
        Sets a persistent variable.

        Returns True on success, False + reporter.error on failure.

        May raise exception if the variable name is invalid or something
        unexpected happens.
        """
        sFull = self.__persistentVarCalcName(sVar);
        try:
            oFile = open(sFull, 'w');
            if len(sValue) > 0:
                oFile.write(sValue.encode('utf-8'));
            oFile.close();
        except:
            reporter.errorXcpt('Error creating "%s"' % (sFull,));
            return False;
        return True;

    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;

    def testImportOva(self, sOva):
        """ xxx """
        oVirtualBox = self.oTstDrv.oVBoxMgr.getVirtualBox();

        #
        # Import it as OVA.
        #
        try:
            oAppliance = oVirtualBox.createAppliance();
        except:
            return reporter.errorXcpt('IVirtualBox::createAppliance failed');

        try:
            oProgress = vboxwrappers.ProgressWrapper(oAppliance.read(sOva), self.oTstDrv.oVBoxMgr, self.oTstDrv,
                                                     'read "%s"' % (sOva,));
        except:
            return reporter.errorXcpt('IAppliance::read("%s") failed' % (sOva,));
        oProgress.wait();
        if oProgress.logResult() is False:
            return False;

        try:
            oAppliance.interpret();
        except:
            return reporter.errorXcpt('IAppliance::interpret() failed on "%s"' % (sOva,));

        #
        try:
            oProgress = vboxwrappers.ProgressWrapper(oAppliance.importMachines([]),
                                                     self.oTstDrv.oVBoxMgr, self.oTstDrv, 'importMachines "%s"' % (sOva,));
        except:
            return reporter.errorXcpt('IAppliance::importMachines failed on "%s"' % (sOva,));
        oProgress.wait();
        if oProgress.logResult() is False:
            return False;

        #
        # Export the
        #
        ## @todo do more with this OVA. Like untaring it and loading it as an OVF.  Export it and import it again.

        return True;

    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;