src/base/test/android/javatests/src/org/chromium/base/test/util/PerfTest.java

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 package org.chromium.base.test.util;
   6
   7 import java.lang.annotation.ElementType;
   8 import java.lang.annotation.Retention;
   9 import java.lang.annotation.RetentionPolicy;
  10 import java.lang.annotation.Target;
  11
  12 /**
  13  * This annotation tells the test harness that this method will be used in a performance test.
  14  * This means that the test harness will use the parameters here to figure out which trace calls
  15  * to track specifically for this test.
  16  * <p>
  17  * Each of the lists ({@link #traceNames()}, {@link #graphNames()},
  18  * and {@link #seriesNames()}) should have the same number of
  19  * elements.
  20  * <p>
  21  * To write a performance test, you need to do the following:
  22  * <p><ol>
  23  * <li>Add TraceEvent calls to the code that you want to track.
  24  *   <ul>
  25  *   <li> For FPS, add a TraceEvent.instant call where you want to time and detect calls.
  26  *   <li> For code segment timing, add {@link org.chromium.base.TraceEvent#begin()}/
  27  * {@link org.chromium.base.TraceEvent#end()} calls around the code
  28  * segment (does not have to be in the same method).
  29  *   </ul>
  30  * <li> Write a Java Automated UI Test that instruments this code.
  31  * <li> Add this PerfTest annotation to the test method.
  32  *   <ul>
  33  *   <li> traceNames must be a list of the names of all of the TraceEvent calls you want to track.
  34  *   <li> graphNames must be a list, one for each traceName, of which graph the trace data should be
  35  *   placed in (does not have to be unique).
  36  *   <li> seriesNames must be a list, one for each traceName, of what the series should be called
  37  *   for this trace data (has to be unique per graphName).
  38  * <li> When checked in, the buildbots will automatically run this test and the results will show up
  39  * under the Java Automation UI Performance graph, where there will be tabs for each graphName
  40  * specified.
  41  * <li> To test your performance test, run the following command and you should see the performance
  42  * numbers printed to the console.
  43  * </ol>
  44  */
  45 @Retention(RetentionPolicy.RUNTIME)
  46 @Target({ElementType.METHOD})
  47 public @interface PerfTest {
  48     /**
  49      * @return A list of the trace calls to track.
  50      */
  51     public String[] traceNames();
  52
  53     /**
  54      * @return A list, one for each traceName, that represents which graph this trace call should
  55      *         be output on.  This does not have to be unique if there are multiple series per
  56      *         graph.
  57      */
  58     public String[] graphNames();
  59
  60     /**
  61      * @return A list, one for each traceName, that represents the series this trace call should be
  62      *         on the corresponding graph.  This should be unique.
  63      */
  64     public String[] seriesNames();
  65
  66     /**
  67      * @return Whether or not we should automatically start and stop tracing for the test.  This
  68      *         makes it easier to run some tests where tracing is started and stopped at the
  69      *         beginning and end of that particular test.
  70      */
  71     public boolean autoTrace() default false;
  72
  73     /**
  74      * @return Whether this performance test should track memory usage in addition to time.  If
  75      *         true, this will track memory usage when tracking time deltas or instants.  With each
  76      *         graph defined in the annotation for tracking time, this will add an additional graph
  77      *         suffixed with a memory identifier containing the same series as those tracking the
  78      *         timing performance but instead will be tracking memory consumption.
  79      */
  80     public boolean traceMemory() default true;
  81
  82     /**
  83      * @return Whether this performance test should track time or (optionally) only memory.  If
  84      *         false, this will not automatically track time deltas or instants when logging
  85      *         memory info.
  86      */
  87     public boolean traceTiming() default true;
  88 }