Home | History | Annotate | Download | only in dx-tests 
      1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
      2 
      3 <html>
      4   <head>
      5     <title>DX Converter Test Suite</title>
      6     <link rel=stylesheet href="dx-tests.css">
      7   </head>
      8 
      9   <body>
     10     <h1>DX Converter Test Suite</h1>
     11     <p>Version 1.0</p>
     12     <p>Copyright &copy; 2008 The Android Open Source Project
     13 
     14     <h2>Overview</h2>
     15 
     16     <p>    
     17       This directory contains a test suite for the DX converter. It tests the
     18       capabilities of the DX converter in a black-box manner, based on the
     19       usual specifications for <code>.class</code> files. The suite does both
     20       functional and verifier tests. Regarding the latter, the DX converter has
     21       only limited bytecode verification capabilities, but the combination of DX
     22       and the Dalvik VM is supposed to perform bytecode verification equivalent
     23       to that done in other virtual machines. Please see
     24         
     25       <pre>
     26         docs/dalvik/java-constraints.html
     27         docs/dalvik/verifier.html
     28       </pre>
     29         
     30       for further details.
     31     </p>
     32 
     33     <h2>How to build</h2>
     34     
     35     <p>
     36       The test suite is normally included in a full build of the Android
     37       project. If it needs to be built individually, a simple
     38         
     39       <pre>
     40         make dx-tests
     41       </pre>
     42         
     43       or an
     44         
     45       <pre>
     46         mm
     47       </pre>
     48         
     49       in this directory will do.
     50     </p>
     51 
     52     <h2>How to run</h2>
     53         
     54     <p>
     55       The suite can be invoked by executing
     56     
     57       <pre>
     58         dx-tests
     59       </pre>
     60     
     61       from any location, assuming the suite has been built. This will run
     62       all tests. If you want to limit the suite to the test cases
     63       corresponding to a single instruction, you can specifiy the mnemonic
     64       as a parameter. For example
     65 
     66       <pre>
     67         dx-tests anewarray
     68       </pre>
     69       
     70       executes the tests for the <code>anewarray</code> instruction.
     71       Please see the corresponding specification for all the mnemonics. Two
     72       additional parameters are possible that don't represent instructions.
     73       These run sanity checks for the suite itself and general verifier tests,
     74       respectively: 
     75 
     76       <pre>
     77         dx-tests sanity
     78         dx-tests verifier
     79       </pre>
     80 
     81       The suite is normally run for the fast version of the interpreter. To run
     82       it for the portable interpreter, pass <code>--portable</code> as the first
     83       parameter. Passing <code>--help</code> results in a brief overview of the
     84       options.
     85     </p>
     86 
     87     <p>      
     88       The suite is compatible with both emulator and simulator 
     89       builds. For an emulator build, please make sure you have
     90       either an emulator running or a device attached via USB before
     91       invoking the test suite.
     92     </p>
     93 
     94     <p>
     95       The suite might easily take 30 minutes or more for execution,
     96       depending on the environment. It will generate a full HTML
     97       report with details on all test cases. While running, console output
     98       is produced to give a quick impression of the progress and results.
     99       For both types of output, each individual test results falls into one of
    100       the following categories:
    101     </p>
    102             
    103     <table>
    104       <tr>
    105         <th>Type in report</th><th>Type on console</th><th>Description</th>
    106       </tr>
    107       <tr>
    108         <td>Success</td>
    109         <td>.</td>
    110         <td>
    111           The test case passed successfully.
    112         </td>
    113       </tr>
    114       <tr>
    115         <td>Functional failure</td>
    116         <td>F</td>
    117         <td>
    118           A functional (normal or boundary) or an exception test case
    119           failed.
    120         </td>
    121         </tr>
    122         <tr>
    123           <td>Verifier failure</td>
    124           <td>V</td>
    125           <td>
    126             A verifier test case failed. Either the verifier accepted
    127             some invalid piece of code or it rejected a valid one.
    128           </td>
    129         </tr>
    130         <tr>
    131           <td>Warning</td>
    132           <td>W</td>
    133           <td>
    134             A verifier test case threw <code>VerifyError</code>, where a
    135             different VM would have thrown a different exception. This is
    136             specified Dalvik behavior, though, hence just the warning.
    137           </td>
    138         </tr>
    139       </table> 
    140   </body>
    141 </html>
    142