| /* |
| * Copyright 2008 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.benchmarks.client; |
| |
| import com.google.gwt.benchmarks.BenchmarkShell; |
| import com.google.gwt.benchmarks.client.impl.BenchmarkResults; |
| import com.google.gwt.junit.PropertyDefiningStrategy; |
| import com.google.gwt.junit.JUnitShell.Strategy; |
| import com.google.gwt.junit.client.GWTTestCase; |
| import com.google.gwt.junit.client.impl.JUnitResult; |
| |
| import junit.framework.TestCase; |
| |
| /** |
| * A type of {@link com.google.gwt.junit.client.GWTTestCase} which specifically |
| * records performance results. {@code Benchmarks} have additional functionality |
| * above and beyond GWT's JUnit support for standard <code>TestCases</code>. |
| * |
| * <h2>Reporting</h2> |
| * <p> |
| * 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>. |
| * </p> |
| * |
| * <h2>Permutations</h2> |
| * <p> |
| * 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 {@code Range} annotation such as {@link RangeField} |
| * or {@link RangeEnum}. |
| * |
| * For example, |
| * |
| * <code><pre> |
| * public void testArrayListRemoves( |
| * @RangeEnum(Position.class) Position where, |
| * @RangeField("insertRemoveRange") Integer size) { ... |
| * } |
| * </pre></code> |
| * </p> |
| * |
| * <h2>Timing</h2> |
| * <ul> |
| * <li>GWT automatically removes jitter from your benchmark methods by running |
| * them for a minimum period of time (150ms).</li> |
| * |
| * <li>GWT supports {@link IterationTimeLimit 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. </li> |
| * |
| * <li>GWT supports {@link Setup} and {@link Teardown} methods which separate |
| * test overhead from the actual work being benchmarked. The timings of these |
| * lifecycle methods are excluded from test results. </li> |
| * </ul> |
| * |
| * <h2>Notes</h2> |
| * <p> |
| * Please note that {@code Benchmarks} 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> |
| * <code>AllocBenchmark</code> 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} |
| * |
| * <h3>An advanced benchmark example</h3> |
| * <code>ArrayListBenchmark</code> is a more sophisticated example of |
| * benchmarking. It demonstrates the use of {@code Setup} and {@code Teardown} |
| * test methods, parameterized test methods, and time limits. |
| * |
| * {@example com.google.gwt.examples.benchmarks.ArrayListBenchmark} |
| */ |
| 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"; |
| |
| /** |
| * The {@link Strategy} used for benchmarking. |
| */ |
| public static class BenchmarkStrategy extends PropertyDefiningStrategy { |
| public BenchmarkStrategy(TestCase test) { |
| super(test); |
| } |
| |
| @Override |
| public String getModuleInherit() { |
| return "com.google.gwt.benchmarks.Benchmarks"; |
| } |
| |
| @Override |
| public void processResult(TestCase testCase, JUnitResult result) { |
| super.processResult(testCase, result); |
| if (result instanceof BenchmarkResults) { |
| BenchmarkShell.getReport().addBenchmarkResults(testCase, |
| (BenchmarkResults) result); |
| } |
| } |
| |
| @Override |
| protected String getBaseModuleExtension() { |
| return "Benchmarks"; |
| } |
| } |
| |
| @Override |
| protected Strategy createStrategy() { |
| return new BenchmarkStrategy(this); |
| } |
| |
| /** |
| * Runs the test via the {@link com.google.gwt.benchmarks.BenchmarkShell} |
| * environment. Do not override or call this method. |
| */ |
| @Override |
| protected final void runTest() throws Throwable { |
| BenchmarkShell.runTest(this, testResult); |
| } |
| |
| /** |
| * Benchmarks do not support asynchronous mode. |
| */ |
| @Override |
| protected final boolean supportsAsync() { |
| return false; |
| } |
| |
| } |