public abstract class

Benchmark

extends GWTTestCase
java.lang.Object
   ↳ TestCase
     ↳ com.google.gwt.junit.client.GWTTestCase
       ↳ com.google.gwt.benchmarks.client.Benchmark

Class Overview

A type of GWTTestCase which specifically records performance results. Benchmarks have additional functionality above and beyond GWT's JUnit support for standard TestCases.

Reporting

In a single JUnit run, the results of all executed benchmarks are collected and stored in an XML report viewable with the benchmarkViewer.

Permutations

GWT supports test methods that have parameters. GWT will execute each benchmark method multiple times in order to exhaustively test all the possible combinations of parameter values. All of your test method parameters must be annotated with a Range annotation such as RangeField or RangeEnum. For example, 

 
 public void testArrayListRemoves(
   @RangeEnum(Position.class) Position where, 
   @RangeField("insertRemoveRange") Integer size) { ... 
 }

Timing

  • GWT automatically removes jitter from your benchmark methods by running them for a minimum period of time (150ms).
  • GWT supports time limits on the maximum duration of each permutation of a benchmark method. With this feature, you can supply very high upper bounds on your ranges (such as Integer.MAX_VALUE), which future-proofs your benchmarks against faster hardware.
  • GWT supports Setup and Teardown methods which separate test overhead from the actual work being benchmarked. The timings of these lifecycle methods are excluded from test results.

Notes

Please note that Benchmarks do not currently support asynchronous testing mode. Calling delayTestFinish(int) or finishTest() will result in an UnsupportedOperationException.

Examples of benchmarking in action

A simple benchmark example

AllocBenchmark is an example of a basic benchmark that doesn't take advantage of most of benchmarking's advanced features. {@example com.google.gwt.examples.benchmarks.AllocBenchmark}

An advanced benchmark example

ArrayListBenchmark is a more sophisticated example of benchmarking. It demonstrates the use of Setup and Teardown test methods, parameterized test methods, and time limits. {@example com.google.gwt.examples.benchmarks.ArrayListBenchmark}

Summary

Nested Classes
class Benchmark.BenchmarkStrategy The JUnitShell.Strategy used for benchmarking. 
Constants
String REPORT_PATH The name of the system property that specifies the location where benchmark reports are both written to and read from.
[Expand]
Inherited Fields
From class com.google.gwt.junit.client.GWTTestCase
Public Constructors
Benchmark()
Protected Methods
JUnitShell.Strategy createStrategy()
Creates the test strategy to use (see getStrategy()).
final void runTest()
Runs the test via the BenchmarkShell environment.
final boolean supportsAsync()
Benchmarks do not support asynchronous mode.
[Expand]
Inherited Methods
From class com.google.gwt.junit.client.GWTTestCase
From class java.lang.Object

Constants

public static final String REPORT_PATH

The name of the system property that specifies the location where benchmark reports are both written to and read from. Its value is com.google.gwt.junit.reportPath. If this system property is not set, the path defaults to the user's current working directory.

Constant Value: "com.google.gwt.junit.reportPath"

Public Constructors

public Benchmark ()

Protected Methods

protected JUnitShell.Strategy createStrategy ()

Creates the test strategy to use (see getStrategy()).

protected final void runTest ()

Runs the test via the BenchmarkShell environment. Do not override or call this method.

Throws
Throwable

protected final boolean supportsAsync ()

Benchmarks do not support asynchronous mode.