<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>DX Converter Test Suite</title>
<link rel=stylesheet href="dx-tests.css">
</head>
<body>
<h1>DX Converter Test Suite</h1>
<p>Version 1.0</p>
<p>Copyright © 2008 The Android Open Source Project
<h2>Overview</h2>
<p>
This directory contains a test suite for the DX converter. It tests the
capabilities of the DX converter in a black-box manner, based on the
usual specifications for <code>.class</code> files. The suite does both
functional and verifier tests. Regarding the latter, the DX converter has
only limited bytecode verification capabilities, but the combination of DX
and the Dalvik VM is supposed to perform bytecode verification equivalent
to that done in other virtual machines. Please see
<pre>
docs/dalvik/java-constraints.html
docs/dalvik/verifier.html
</pre>
for further details.
</p>
<h2>How to build</h2>
<p>
The test suite is normally included in a full build of the Android
project. If it needs to be built individually, a simple
<pre>
make dx-tests
</pre>
or an
<pre>
mm
</pre>
in this directory will do.
</p>
<h2>How to run</h2>
<p>
The suite can be invoked by executing
<pre>
dx-tests
</pre>
from any location, assuming the suite has been built. This will run
all tests. If you want to limit the suite to the test cases
corresponding to a single instruction, you can specifiy the mnemonic
as a parameter. For example
<pre>
dx-tests anewarray
</pre>
executes the tests for the <code>anewarray</code> instruction.
Please see the corresponding specification for all the mnemonics. Two
additional parameters are possible that don't represent instructions.
These run sanity checks for the suite itself and general verifier tests,
respectively:
<pre>
dx-tests sanity
dx-tests verifier
</pre>
The suite is normally run for the fast version of the interpreter. To run
it for the portable interpreter, pass <code>--portable</code> as the first
parameter. Passing <code>--help</code> results in a brief overview of the
options.
</p>
<p>
The suite is compatible with both emulator and simulator
builds. For an emulator build, please make sure you have
either an emulator running or a device attached via USB before
invoking the test suite.
</p>
<p>
The suite might easily take 30 minutes or more for execution,
depending on the environment. It will generate a full HTML
report with details on all test cases. While running, console output
is produced to give a quick impression of the progress and results.
For both types of output, each individual test results falls into one of
the following categories:
</p>
<table>
<tr>
<th>Type in report</th><th>Type on console</th><th>Description</th>
</tr>
<tr>
<td>Success</td>
<td>.</td>
<td>
The test case passed successfully.
</td>
</tr>
<tr>
<td>Functional failure</td>
<td>F</td>
<td>
A functional (normal or boundary) or an exception test case
failed.
</td>
</tr>
<tr>
<td>Verifier failure</td>
<td>V</td>
<td>
A verifier test case failed. Either the verifier accepted
some invalid piece of code or it rejected a valid one.
</td>
</tr>
<tr>
<td>Warning</td>
<td>W</td>
<td>
A verifier test case threw <code>VerifyError</code>, where a
different VM would have thrown a different exception. This is
specified Dalvik behavior, though, hence just the warning.
</td>
</tr>
</table>
</body>
</html>