tests/org.eclipse.test.performance/src/org/eclipse/test/performance/PerformanceTestCase.java

/*******************************************************************************
 * Copyright (c) 2004, 2005 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.test.performance;

import junit.framework.TestCase;

/**
 * A PerformanceTestCase is a convenience class that takes care of managing
 * a <code>PerformanceMeter</code>.
 * <p>
 * Here is an example:
 * <pre>
 * public class MyPerformanceTestCase extends PeformanceTestCase {
 * 		
 *   public void testMyOperation() {
 *     for (int i= 0; i < 10; i++) {
 *       startMeasuring();
 *       // my operation
 *       stopMeasuring();
 *     }
 *     commitMeasurements();
 *     assertPerformance();
 *   }	
 * }
 */
public class PerformanceTestCase extends TestCase {

	protected PerformanceMeter fPerformanceMeter;

	/**
	 * Constructs a performance test case.
	 */
	public PerformanceTestCase() {
		super();
	}

	/**
	 * Constructs a performance test case with the given name.
	 * @param name the name of the performance test case
	 */
	public PerformanceTestCase(String name) {
		super(name);
	}
	
	/**
	 * Overridden to create a default performance meter for this test case.
	 * @throws Exception
	 */
	protected void setUp() throws Exception {
		Performance performance= Performance.getDefault();
		fPerformanceMeter= performance.createPerformanceMeter(performance.getDefaultScenarioId(this));
	}

	/**
	 * Overridden to dispose of the performance meter.
	 * @throws Exception
	 */
	protected void tearDown() throws Exception {
		fPerformanceMeter.dispose();
	}

	/**
	 * Mark the scenario of this test case
	 * to be included into the global and the component performance summary. The summary shows
	 * the given dimension of the scenario and labels the scenario with the short name.
	 * 
	 * @param shortName a short (shorter than 40 characters) descritive name of the scenario
	 * @param dimension the dimension to show in the summary
	 */
	public void tagAsGlobalSummary(String shortName, Dimension dimension) {
		Performance performance= Performance.getDefault();
		performance.tagAsGlobalSummary(fPerformanceMeter, shortName, new Dimension[] { dimension } );
	}

	/**
	 * Mark the scenario represented by the given PerformanceMeter
	 * to be included into the global and the component performance summary. The summary shows
	 * the given dimensions of the scenario and labels the scenario with the short name.
	 * 
	 * @param shortName a short (shorter than 40 characters) descritive name of the scenario
	 * @param dimensions an array of dimensions to show in the summary
	 */
	public void tagAsGlobalSummary(String shortName, Dimension[] dimensions) {
		Performance performance= Performance.getDefault();
		performance.tagAsGlobalSummary(fPerformanceMeter, shortName, dimensions );
	}
	
	/**
	 * Mark the scenario of this test case
	 * to be included into the component performance summary. The summary shows
	 * the given dimension of the scenario and labels the scenario with the short name.
	 * 
	 * @param shortName a short (shorter than 40 characters) descritive name of the scenario
	 * @param dimension the dimension to show in the summary
	 */
	public void tagAsSummary(String shortName, Dimension dimension) {
		Performance performance= Performance.getDefault();
		performance.tagAsSummary(fPerformanceMeter, shortName, new Dimension[] { dimension } );
	}

	/**
	 * Mark the scenario represented by the given PerformanceMeter
	 * to be included into the component performance summary. The summary shows
	 * the given dimensions of the scenario and labels the scenario with the short name.
	 * 
	 * @param shortName a short (shorter than 40 characters) descritive name of the scenario
	 * @param dimensions an array of dimensions to show in the summary
	 */
	public void tagAsSummary(String shortName, Dimension[] dimensions) {
		Performance performance= Performance.getDefault();
		performance.tagAsSummary(fPerformanceMeter, shortName, dimensions );
	}
	
	/**
	 * Set a comment for the scenario represented by this TestCase.
	 * Currently only comments with a commentKind of EXPLAINS_DEGRADATION_COMMENT are used.
	 * Their commentText is shown in a hover of the performance summaries graph if a performance
	 * degradation exists.
	 * 
	 * @param commentKind kind of comment. Must be EXPLAINS_DEGRADATION_COMMENT to have an effect.
	 * @param commentText the comment (shorter than 400 characters)
	 */
	public void setComment(int commentKind, String commentText) {
		Performance performance= Performance.getDefault();
		performance.setComment(fPerformanceMeter, commentKind, commentText);
	}
	
	/**
	 * Called from within a test case immediately before the code to measure is run.
	 * It starts capturing of performance data.
	 * Must be followed by a call to {@link PerformanceTestCase#stopMeasuring()} before subsequent calls
	 * to this method or {@link PerformanceTestCase#commitMeasurements()}.
	 */
	protected void startMeasuring() {
		fPerformanceMeter.start();
	}
	
	protected void stopMeasuring() {
		fPerformanceMeter.stop();
	}
	
	protected void commitMeasurements() {
		fPerformanceMeter.commit(); 
	}

	/**
	 * Asserts default properties of the measurements captured for this test case.
	 * 
	 * @throws RuntimeException if the properties do not hold
	 */
	protected void assertPerformance() {
		Performance.getDefault().assertPerformance(fPerformanceMeter);
	}

	/**
	 * Asserts that the measurement specified by the given dimension
	 * is within a certain range with respect to some reference value.
	 * If the specified dimension isn't available, the call has no effect.
	 * 
	 * @param dim the Dimension to check
	 * @param lowerPercentage a negative number indicating the percentage the measured value is allowed to be smaller than some reference value
	 * @param upperPercentage a positive number indicating the percentage the measured value is allowed to be greater than some reference value
	 * @throws RuntimeException if the properties do not hold
	 */
	protected void assertPerformanceInRelativeBand(Dimension dim, int lowerPercentage, int upperPercentage) {
		Performance.getDefault().assertPerformanceInRelativeBand(fPerformanceMeter, dim, lowerPercentage, upperPercentage);
	}
}