# JBoss, Home of Professional Open Source # Copyright 2010, 2011 Red Hat, Inc. and/or its affiliates, # and individual contributors as indicated by the @author tags. # See the copyright.txt in the distribution for a # full listing of individual contributors. # This copyrighted material is made available to anyone wishing to use, # modify, copy, or redistribute it subject to the terms and conditions # of the GNU Lesser General Public License, v. 2.1. # This program is distributed in the hope that it will be useful, but WITHOUT A # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A # PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. # You should have received a copy of the GNU Lesser General Public License, # v.2.1 along with this distribution; if not, write to the Free Software # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, # MA 02110-1301, USA. # # (C) 2010-11, # @author JBoss, by Red Hat. # @author Andrew Dinn (adinn@redhat.com) 2010-11 File ---- README.txt for Byteman contrib BMUnit Summary ------- BMUnit is a user package which automates loading of Byteman rules into JUnit or TestNG tests. Usage Guide ----------- This package simplifies use of Byteman in JUnit and TestNG tests. It provides two annotations, BMRule and BMScript, which you attach either to a test class or to a test method. These annotations specify, respectively, the text of a Byteman rule or the location of a Byteman rule script file which should be installed before running your tests and deinstalled after the tests have completed. Class annotations identify rules which should be present for all tests in the class. These rules are loaded before running any of the class's test methods and only unloaded once all test methods have been executed. Method annoations identify rules required for a specifc test. They are loaded just before the test method gets called and unloaded after it has finished (or failed) before executing the next test method. The package also provides two grouping annotations, BMScripts and BMRules, which allow multiple BMScript or BMRules annotations to be attached to a class or method. These grouping annotations contain a field whose value is an array of BMScript or BMRule annotations, respectively. TestNG Style Tests ------------------ Your test class should extend class BMNGRunner.It then inherits Before/AfterClass and Before/AfterMethod behaviour which loads the Byteman agent on demand and loads and unloads rules in response to the presence of @BMScript, @BMScripts, @BMRule or @BMRules annotations. JUnit 4 Style Tests ------------------- Your test class should be annotated with @RunWith(BMUnitRunner). The runner will load the Byteman agent on demand and will load and unload rules in response to the presence of @BMScript, @BMScripts, @BMRule or @BMRules annotations. @BMScript(s) annotation ----------------------- A @BMScript annotation is used to load rules from a script file. It can be configured with a directory name (field dir) and a test name (field value). If not supplied these values will be defaulted and the rule file is searched for in a series of standard locations. The test will fail if the script cannot be found. Multiple scripts can be specified using the @BMScripts annotation whose scripts field can be initialised with a series of @BMScript annotations. The name of a class rules script file is determined using the annotation value and the test class name or, if the value is omitted, just the class name. The name of a method rule script file is determined using the annotation value and the test class name or, if the value is omitted, the method name and class name (exact details follow below). The directory from which to search for scripts can be configured using the dir field of the BMScript annotation. If it is left unconfigured then the default location is used (exact details follow below). @BMRule(s) annotation --------------------- A @BMRule annotation can be used to specify the text of a single rule. Annotation fields define the target class, method, location, etc. Multiple rules can be specified using the @BMRules annotation whose rules field can be initialised with a series of @BMRule annotations. These annotations may be attached to either the test class or a test method but their use at each location is exclusive i.e. it is not legitimate for a class to be annotated with both annotations, ditto for a test method. These annotations may also be used in combination with @BMScript annotations. Note that @BMScript rules are always loaded before rules specified via @BMRule. @BMScript file Lookup --------------------- File lookup employs the computed test name and/or the test class name to locate the rule script, trying various alternative combinations of these two values. If you have configured a lookup directory then files are searched for below that directory. Otherwise, System property org.jboss.byteman.contrib.bmunit.script.directory will be checked and, if set, used as the search directory. Failing that the search will proceed using the working directory of the test. Files are searched for as follows: Let testName be the test name ("" or null means cases with * are ignored) org.my.TestCaseClass be the name of the test class