| /* | |
| * Copyright 2007 Google Inc. | |
| * | |
| * Licensed under the Apache License, Version 2.0 (the "License"); you may not | |
| * use this file except in compliance with the License. You may obtain a copy of | |
| * the License at | |
| * | |
| * http://www.apache.org/licenses/LICENSE-2.0 | |
| * | |
| * Unless required by applicable law or agreed to in writing, software | |
| * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT | |
| * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the | |
| * License for the specific language governing permissions and limitations under | |
| * the License. | |
| */ | |
| package com.google.gwt.junit.client; | |
| /** | |
| * A type of {@link com.google.gwt.junit.client.GWTTestCase} which specifically | |
| * records performance results. {@link com.google.gwt.junit.client.Benchmark}s | |
| * have additional functionality above and beyond GWT's JUnit support for | |
| * standard <code>TestCases</code>. | |
| * | |
| * <ul> | |
| * <li>In a single <code>JUnit</code> run, the results of all executed | |
| * benchmarks are collected and stored in an XML report viewable with the | |
| * <code>benchmarkViewer</code>.</li> | |
| * | |
| * <li>GWT automatically removes jitter from your benchmark methods by running | |
| * them for a minimum period of time (150ms). GWT also optionally limits your | |
| * benchmark execution to a maximum period of time (1000ms).</li> | |
| * | |
| * <li>GWT supports "begin" and "end" test methods that separate setup and | |
| * teardown costs from the actual work being benchmarked. Simply name your | |
| * functions "begin[TestMethodName]" and "end[TestMethodName]" and they will | |
| * be executed before and after every execution of your test method. The | |
| * timings of these setup methods are not included in the test results.</li> | |
| * | |
| * <li>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. For each parameter that your test method | |
| * accepts, it should document it with the annotation, | |
| * <code>@gwt.benchmark.param</code>. | |
| * | |
| * <p>The syntax for gwt.benchmark.param is | |
| * <code><param name> = <Iterable></code>. For example, | |
| * | |
| * <pre> | |
| * @gwt.benchmark.param where = java.util.Arrays.asList( | |
| * new Position[] { Position.BEGIN, Position.END, Position.VARIED } ) | |
| * @gwt.benchmark.param size -limit = insertRemoveRange | |
| * public void testArrayListRemoves(Position where, Integer size) { ... } | |
| * </pre></p> | |
| * | |
| * <p>In this example, the annotated function is executed with all the possible | |
| * permutations of <code>Position = (BEGIN, END, and VARIED)</code> and | |
| * <code>insertRemoveRange = IntRange( 64, Integer.MAX_VALUE, "*", 2 )</code>. | |
| * </p> | |
| * | |
| * <p>This particular example also demonstrates how GWT can automatically limit | |
| * the number of executions of your test. Your final parameter (in this example, | |
| * size) can optionally be decorated with -limit to indicate to GWT that | |
| * it should stop executing additional permutations of the test when the | |
| * execution time becomes too long (over 1000ms). So, in this example, | |
| * for each value of <code>Position</code>, <code>testArrayListRemoves</code> | |
| * will be executed for increasing values of <code>size</code> (beginning with | |
| * 64 and increasing in steps of 2), until either it reaches | |
| * <code>Integer.MAX_VALUE</code> or the execution time for the last | |
| * permutation is > 1000ms.</p> | |
| * </li> | |
| * </ul> | |
| * | |
| * <p>{@link Benchmark}s support the following annotations on each test method | |
| * in order to decorate each test with additional information useful for | |
| * reporting.</p> | |
| * | |
| * <ul> | |
| * <li><code>@gwt.benchmark.category</code> - The class name of the {@link Category} the | |
| * benchmark belongs to. This property may also be set at the | |
| * {@link com.google.gwt.junit.client.Benchmark} class level.</li> | |
| * </ul> | |
| * | |
| * <p>Please note that {@link Benchmark}s do not currently support asynchronous | |
| * testing mode. Calling | |
| * {@link com.google.gwt.junit.client.GWTTestCase#delayTestFinish(int)} | |
| * or {@link com.google.gwt.junit.client.GWTTestCase#finishTest()} will result | |
| * in an UnsupportedOperationException.</p> | |
| * | |
| * <h2>Examples of benchmarking in action</h2> | |
| * | |
| * <h3>A simple benchmark example</h3> | |
| * {@link com.google.gwt.examples.benchmarks.AllocBenchmark} is a simple example | |
| * of a basic benchmark that doesn't take advantage of most of benchmarking's | |
| * advanced features. | |
| * | |
| * {@example com.google.gwt.examples.benchmarks.AllocBenchmark} | |
| * | |
| * <h3>An advanced benchmark example</h3> | |
| * {@link com.google.gwt.examples.benchmarks.ArrayListAndVectorBenchmark} is a more | |
| * sophisticated example of benchmarking. It demonstrates the use of "begin" | |
| * and "end" test methods, parameterized test methods, and automatic | |
| * test execution limits. | |
| * | |
| * {@example com.google.gwt.examples.benchmarks.ArrayListAndVectorBenchmark} | |
| */ | |
| public abstract class Benchmark extends GWTTestCase { | |
| /** | |
| * The name of the system property that specifies the location | |
| * where benchmark reports are both written to and read from. | |
| * Its value is <code>com.google.gwt.junit.reportPath</code>. | |
| * | |
| * If this system property is not set, the path defaults to the user's | |
| * current working directory. | |
| */ | |
| public static final String REPORT_PATH = "com.google.gwt.junit.reportPath"; | |
| } |