summaryrefslogtreecommitdiffstats
path: root/src/VBox/ValidationKit/docs/VBoxValidationKitReadMe.txt
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/VBox/ValidationKit/docs/VBoxValidationKitReadMe.txt113
1 files changed, 113 insertions, 0 deletions
diff --git a/src/VBox/ValidationKit/docs/VBoxValidationKitReadMe.txt b/src/VBox/ValidationKit/docs/VBoxValidationKitReadMe.txt
new file mode 100644
index 00000000..d1c7de60
--- /dev/null
+++ b/src/VBox/ValidationKit/docs/VBoxValidationKitReadMe.txt
@@ -0,0 +1,113 @@
+
+The VirtualBox Validation Kit
+=============================
+
+
+Introduction
+------------
+
+The VirtualBox Validation Kit is our new public tool for doing automated
+testing of VirtualBox. We are continually working on adding new features
+and guest operating systems to our battery of tests.
+
+We warmly welcome contributions, new ideas for good tests and fixes.
+
+
+Directory Layout
+----------------
+
+./docs/
+ The documentation for the test suite mostly lives here, the exception being
+ readme.txt files that are better off living near what they concern.
+
+ For a definition of terms used here, see the Definitions / Glossary section
+ of ./docs/AutomaticTestingRevamp.txt / ./docs/AutomaticTestingRevamp.html.
+
+./testdriver/
+ Python module implementing the base test drivers and supporting stuff.
+ The base test driver implementation is found in ./testdriver/base.py while
+ the VBox centric specialization is in ./testdriver/vbox.py. Various VBox
+ API wrappers that makes things easier to use and glosses over a lot of API
+ version differences that live in ./testdriver/vboxwrappers.py.
+
+ Test VM collections are often managed thru ./testdriver/vboxtestvms.py, but
+ doesn't necessarily have to be, it's up to the individual test driver.
+
+ For logging, reporting result, uploading useful files and such we have a
+ reporter singleton sub-package, ./testdriver/reporter.py. It implements
+ both local (for local testing) and remote (for testboxes + test manager)
+ reporting.
+
+ There is also a VBoxTXS client implementation in txsclient.py and a stacked
+ test driver for installing VBox (vboxinstaller.py). Most test drivers will
+ use the TXS client indirectly thru vbox.py methods. The installer driver
+ is a special trick for the testbox+testmanager setup.
+
+./tests/
+ The python scripts driving the tests. These are organized by what they
+ test and are all derived from the base classes in ./testdriver (mostly from
+ vbox.py of course). Most tests use one or more VMs from a standard set of
+ preconfigured VMs defined by ./testdriver/vboxtestvms.py (mentioned above),
+ though the installation tests used prepared ISOs and floppy images.
+
+./vms/
+ Text documents describing the preconfigured test VMs defined by
+ ./testdrive/vboxtestvms.py. This will also contain description of how to
+ prepare installation ISOs when we get around to it (soon).
+
+./utils/
+ Test utilities and lower level test programs, compiled from C, C++ and
+ Assembly mostly. Generally available for both host and guest, i.e. in the
+ zip and on the VBoxValidationKit.iso respectively.
+
+ The Test eXecution Service (VBoxTXS) found in ./utils/TestExecServ is one
+ of the more important utilities. It implements a remote execution service
+ for running programs/tests inside VMs and on other test boxes. See
+ ./utils/TestExecServ/vboxtxs-readme.txt for more details.
+
+ A simple network bandwidth and latency test program can be found in
+ ./utils/network/NetPerf.cpp.
+
+./bootsectors/
+ Boot sector test environment. This allows creating floppy images in
+ assembly that tests specific CPU or device behavior. Most tests can be
+ put on a USB stick, floppy or similar and booted up on real hardware for
+ comparison. All floppy images can be used for manual testing by developers
+ and most will be used by test drivers (./tests/*/td*.py) sooner or later.
+
+ The boot sector environment is heavily bound to yasm and it's ability to
+ link binary images for single assembly input units. There is a "library"
+ of standard initialization code and runtime code, which include switch to
+ all (well V8086 mode is still missing, but we'll get that done eventually)
+ processor modes and paging modes. The image specific code is split into
+ init/driver code and test template, the latter can be instantiated for each
+ process execution+paging mode.
+
+./common/
+ Python package containing common python code.
+
+./testboxscript/
+ The testbox script. This is installed on testboxes used for automatic
+ testing with the testmanager.
+
+./testmanager/
+ The VirtualBox Test Manager (server side code). This is written in Python
+ and currently uses postgresql as database backend for no particular reason
+ other than that it was already installed on the server the test manager was
+ going to run on. It's relatively generic, though there are of course
+ things in there that are of more use when testing VirtualBox than other
+ things. A more detailed account (though perhaps a little dated) of the
+ test manager can be found in ./docs/AutomaticTestingRevamp.txt and
+ ./docs/AutomaticTestingRevamp.html.
+
+./testanalysis/
+ A start a local test result analysis, comparing network test output. We'll
+ probably be picking this up again later.
+
+./snippets/
+ Various code snippets that may be turned into real tests at some point.
+
+
+
+:Status: $Id: VBoxValidationKitReadMe.txt $
+:Copyright: Copyright (C) 2010-2023 Oracle Corporation.