| Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. |
| DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| |
| This code is free software; you can redistribute it and/or modify it |
| under the terms of the GNU General Public License version 2 only, as |
| published by the Free Software Foundation. |
| |
| This code is distributed in the hope that it will be useful, but WITHOUT |
| ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| version 2 for more details (a copy is included in the LICENSE file that |
| accompanied this code). |
| |
| You should have received a copy of the GNU General Public License version |
| 2 along with this work; if not, write to the Free Software Foundation, |
| Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| |
| Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| or visit www.oracle.com if you need additional information or have any |
| questions. |
| |
| |
| |
| DESCRIPTION |
| |
| The purpose of this library is gathering diagnostic information on test |
| failures and timeouts. The library runs platform specific tools, which are |
| configured in the way described below. The collected data will be available |
| in HTML format next to JTR files. |
| |
| The library uses JTHarness Observer and jtreg TimeoutHandler extensions points. |
| |
| DEPENDENCES |
| |
| The library requires jtreg 4b13+ and JDK 7+. |
| |
| BUILDING |
| |
| To build a library, one should simply run make with 'JTREG_HOME' and |
| 'JAVA_HOME' environment variables set. 'JAVA_HOME' should contain path to JDK, |
| 'JTREG_HOME' -- path to jtreg. |
| |
| 'image/lib/jtregFailureHandler.jar' is created on successful build. |
| |
| CONFIGURATION |
| |
| Properties files are used to configure the library. They define which actions |
| to be performed in case of individual test failure or timeout. Each platform |
| family uses its own property file (named '<platform>.properties'). For platform |
| independent actions, 'common.properties' is used. |
| |
| Actions to be performed on each failure are listed in 'environment' property. |
| Extra actions for timeouts are listed in 'onTimeout'. |
| |
| Each action is defined via the following parameters: |
| - 'javaOnly' -- run the action only for java applications, false by default |
| - 'app' -- an application to run, mandatory parameter |
| - 'args' -- application command line arguments, none by default |
| - 'params' -- a structure which defines how an application should be run, |
| described below |
| |
| Actions listed in 'onTimeout' are "patterned" actions. Besides the parameters |
| listed above, they also have 'pattern' parameter -- a string which will be |
| replaced by PID in 'args' parameter before action execution. |
| |
| 'params' structure has the following parameters: |
| - repeat -- how many times an action will be run, 1 by default |
| - pause -- delay in ms between iterations, 500 by default |
| - timeout -- time limitation for iteration in ms, 20 000 by default |
| - stopOnError -- if true, an action will be interrupted after the first error, |
| false by default |
| |
| From '<platform>.properties', the library reads the following parameters |
| - 'config.execSuffix' -- a suffix for all binary application file names |
| - 'config.getChildren' -- a "patterned" action used to get the list of all |
| children |
| |
| For simplicity we use parameter values inheritance. This means that we are |
| looking for the most specified parameter value. If we do not find it, we are |
| trying to find less specific value by reducing prefix. |
| For example, if properties contains 'p1=A', 'a.p1=B', 'a.b.p1=C', then |
| parameter 'p1' will be: |
| - 'C' for 'a.b.c' |
| - 'B' for 'a.c' |
| - 'A' for 'b.c' |
| |
| RUNNING |
| |
| To enable the library in jtreg, the following options should be set: |
| - '-timeoutHandlerDir' points to the built jar ('jtregFailureHandler.jar') |
| - '-observerDir' points to the built jar |
| - '-timeoutHandler' equals to jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler |
| - '-observer' equals to jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver |
| |
| In case of environment issues during an action execution, such as missing |
| application, hung application, lack of disk space, etc, the corresponding |
| warning appears and the library proceeds to next action. |
| |
| EXAMPLES |
| |
| $ ${JTREG_HOME}/bin/jtreg -jdk:${JAVA_HOME} \ |
| -timeoutHandlerDir:./image/lib/jtregFailureHandler.jar \ |
| -observerDir:./image/lib/jtregFailureHandler.jar \ |
| -timeoutHandler:jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler\ |
| -observer:jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver \ |
| ${WS}/hotspot/test/ |
| |