# Dalvik VM Test Suite

Version 1.0

Copyright © 2008 The Android Open Source Project

## Overview

This directory contains a test suite for the Dalvik VM. It tests the capabilities of the Dalvik VM in a black-box manner, based on the Dalvik bytecode and `.dex` file format specifications. The suite does both functional and verifier tests. Regarding the latter, the Dalvik VM is supposed to perform bytecode verification equivalent to that done in other virtual machines. Please see

            docs/dalvik/dalvik-bytecode.html
            docs/dalvik/dalvik-constraints.html
            docs/dalvik/dex-format.html
            docs/dalvik/verifier.html

for further details.

## How to build

The test suite is normally included in a full build of the Android project. If it needs to be built individually, a simple

            make vm-tests

or an

            mm

in this directory will do.

## How to run

The suite can be invoked by executing

            vm-tests

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

            vm-tests add-int/lit16

executes the tests for the `add-int/lit16` instruction. Please see the Dalvik VM specification for all the mnemonics. Two additional parameters are possible that don't represent instructions. These run integrity tests for the DEX file format and general verifier tests, respectively:

            vm-tests format
            vm-tests verifier

The suite is normally run for the fast version of the interpreter. To run it for the portable interpreter, pass `--portable` as the first parameter. Passing `--help` results in a brief overview of the options.

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.

The full suite might easily take 30 minutes or more for execution, depending on the environment. It will generate an 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 result falls into one of the following categories:

Type in report | Type on console | Description
--- | --- | ---
Success | . | The test case passed successfully.
Functional failure | F | A functional (normal or boundary) or an exception test case failed.
Verifier failure | V | A verifier test case failed. Either the verifier accepted some invalid piece of code or it rejected a valid one.
Console error | C | The process running the VM returned error messages on the standard output or error stream, but it is not clear what the nature of the problem is. The test case is considered a failure, though. This problem should only occur when running the suite on a simulator build.