annotate test/failure_handler/README @ 50842:4d990bb19c99

4475138: getBestCursorSize and XFree86 4.1.0 Reviewed-by: serb Contributed-by:
author serb
date Mon, 25 Jun 2018 17:34:55 -0700
parents b509dfa96469
rev   line source
iignatyev@35016 1 Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
iignatyev@35016 3
iignatyev@35016 4 This code is free software; you can redistribute it and/or modify it
iignatyev@35016 5 under the terms of the GNU General Public License version 2 only, as
iignatyev@35016 6 published by the Free Software Foundation.
iignatyev@35016 7
iignatyev@35016 8 This code is distributed in the hope that it will be useful, but WITHOUT
iignatyev@35016 9 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
iignatyev@35016 10 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
iignatyev@35016 11 version 2 for more details (a copy is included in the LICENSE file that
iignatyev@35016 12 accompanied this code).
iignatyev@35016 13
iignatyev@35016 14 You should have received a copy of the GNU General Public License version
iignatyev@35016 15 2 along with this work; if not, write to the Free Software Foundation,
iignatyev@35016 16 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
iignatyev@35016 17
iignatyev@35016 18 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
iignatyev@35016 19 or visit if you need additional information or have any
iignatyev@35016 20 questions.
iignatyev@35016 21
iignatyev@35016 22
iignatyev@35016 23
iignatyev@35016 24 DESCRIPTION
iignatyev@35016 25
iignatyev@35016 26 The purpose of this library is gathering diagnostic information on test
iignatyev@35016 27 failures and timeouts. The library runs platform specific tools, which are
iignatyev@35016 28 configured in the way described below. The collected data will be available
iignatyev@35016 29 in HTML format next to JTR files.
iignatyev@35016 30
iignatyev@35016 31 The library uses JTHarness Observer and jtreg TimeoutHandler extensions points.
iignatyev@35016 32
iignatyev@35016 33 DEPENDENCES
iignatyev@35016 34
iignatyev@35016 35 The library requires jtreg 4b13+ and JDK 7+.
iignatyev@35016 36
iignatyev@35016 37 BUILDING
iignatyev@35016 38
erikj@37031 39 The library is built using the top level build-test-failure-handler target and
erikj@37031 40 is automatically included in the test image and picked up by hotspot and jdk
erikj@37031 41 test makefiles.
iignatyev@35016 42
iignatyev@35016 43 CONFIGURATION
iignatyev@35016 44
iignatyev@35016 45 Properties files are used to configure the library. They define which actions
iignatyev@35016 46 to be performed in case of individual test failure or timeout. Each platform
iignatyev@35016 47 family uses its own property file (named '<platform>.properties'). For platform
iignatyev@35016 48 independent actions, '' is used.
iignatyev@35016 49
iignatyev@35016 50 Actions to be performed on each failure are listed in 'environment' property.
iignatyev@35016 51 Extra actions for timeouts are listed in 'onTimeout'.
iignatyev@35016 52
iignatyev@35016 53 Each action is defined via the following parameters:
iignatyev@35016 54 - 'javaOnly' -- run the action only for java applications, false by default
iignatyev@35016 55 - 'app' -- an application to run, mandatory parameter
iignatyev@35016 56 - 'args' -- application command line arguments, none by default
iignatyev@35016 57 - 'params' -- a structure which defines how an application should be run,
iignatyev@35016 58 described below
iignatyev@35016 59
iignatyev@35016 60 Actions listed in 'onTimeout' are "patterned" actions. Besides the parameters
iignatyev@35016 61 listed above, they also have 'pattern' parameter -- a string which will be
iignatyev@35016 62 replaced by PID in 'args' parameter before action execution.
iignatyev@35016 63
iignatyev@35016 64 'params' structure has the following parameters:
iignatyev@35016 65 - repeat -- how many times an action will be run, 1 by default
iignatyev@35016 66 - pause -- delay in ms between iterations, 500 by default
iignatyev@35016 67 - timeout -- time limitation for iteration in ms, 20 000 by default
iignatyev@35016 68 - stopOnError -- if true, an action will be interrupted after the first error,
iignatyev@35016 69 false by default
iignatyev@35016 70
iignatyev@35016 71 From '<platform>.properties', the library reads the following parameters
iignatyev@35016 72 - 'config.execSuffix' -- a suffix for all binary application file names
iignatyev@35016 73 - 'config.getChildren' -- a "patterned" action used to get the list of all
iignatyev@35016 74 children
iignatyev@35016 75
iignatyev@35016 76 For simplicity we use parameter values inheritance. This means that we are
iignatyev@35016 77 looking for the most specified parameter value. If we do not find it, we are
iignatyev@35016 78 trying to find less specific value by reducing prefix.
iignatyev@35016 79 For example, if properties contains 'p1=A', 'a.p1=B', 'a.b.p1=C', then
iignatyev@35016 80 parameter 'p1' will be:
iignatyev@35016 81 - 'C' for 'a.b.c'
iignatyev@35016 82 - 'B' for 'a.c'
iignatyev@35016 83 - 'A' for 'b.c'
iignatyev@35016 84
iignatyev@35016 85 RUNNING
iignatyev@35016 86
iignatyev@35016 87 To enable the library in jtreg, the following options should be set:
iignatyev@35016 88 - '-timeoutHandlerDir' points to the built jar ('jtregFailureHandler.jar')
iignatyev@35016 89 - '-observerDir' points to the built jar
iignatyev@35016 90 - '-timeoutHandler' equals to jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler
iignatyev@35016 91 - '-observer' equals to jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver
iignatyev@35016 92
iignatyev@35016 93 In case of environment issues during an action execution, such as missing
iignatyev@35016 94 application, hung application, lack of disk space, etc, the corresponding
iignatyev@35016 95 warning appears and the library proceeds to next action.
iignatyev@35016 96
iignatyev@35016 97 EXAMPLES
iignatyev@35016 98
iignatyev@35016 99 $ ${JTREG_HOME}/bin/jtreg -jdk:${JAVA_HOME} \
iignatyev@35016 100 -timeoutHandlerDir:./image/lib/jtregFailureHandler.jar \
iignatyev@35016 101 -observerDir:./image/lib/jtregFailureHandler.jar \
iignatyev@35016 102 -timeoutHandler:jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler\
iignatyev@35016 103 -observer:jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver \
iignatyev@35016 104 ${WS}/hotspot/test/
iignatyev@35016 105