org.testng
Class TestNG

java.lang.Object
  extended by org.testng.TestNG

public class TestNG
extends java.lang.Object

This class is the main entry point for running tests in the TestNG framework. Users can create their own TestNG object and invoke it in many different ways:

You can also define which groups to include or exclude, assign parameters, etc...

The command line parameters are:

Please consult documentation for more details. FIXME: should support more than simple paths for suite xmls

Author:
Cedric Beust, Alex Popescu
See Also:
usage()

Nested Class Summary
static class TestNG.ExitCodeListener
           
 
Field Summary
static java.lang.String DEFAULT_COMMAND_LINE_SUITE_NAME
          The default name for a suite launched from the command line
static java.lang.String DEFAULT_COMMAND_LINE_TEST_NAME
          The default name for a test launched from the command line
static java.lang.String DEFAULT_OUTPUTDIR
          The default name of the result's output directory.
static int HAS_FAILURE
           
static int HAS_FSP
           
static int HAS_NO_TEST
           
static int HAS_SKIPPED
           
static java.lang.String JAVADOC_ANNOTATION_TYPE
          The JavaDoc annotation type ID ("javadoc").
static java.lang.String JDK_ANNOTATION_TYPE
          The JDK50 annotation type ID ("JDK5").
protected  java.util.List<XmlSuite> m_cmdlineSuites
           
protected  java.lang.String[] m_excludedGroups
           
protected  boolean m_hasTests
           
protected  java.lang.String[] m_includedGroups
           
protected  java.util.List<IInvokedMethodListener> m_invokedMethodListeners
           
protected  IAnnotationFinder m_javadocAnnotationFinder
           
protected  IAnnotationFinder m_jdkAnnotationFinder
           
protected  java.lang.String m_outputDir
           
protected  java.lang.String[] m_sourceDirs
          The source directories as set by setSourcePath (or testng-sourcedir-override.properties).
protected  int m_status
           
protected  java.util.List<ISuiteListener> m_suiteListeners
           
protected  java.util.List<XmlSuite> m_suites
           
protected  java.util.List<ITestListener> m_testListeners
           
protected  ITestRunnerFactory m_testRunnerFactory
           
protected  boolean m_useDefaultListeners
           
static java.lang.String SRC_SEPARATOR
          A separator constant (semi-colon).
 
Constructor Summary
TestNG()
          Default constructor.
TestNG(boolean useDefaultListeners)
          Used by maven2 to have 0 output of any kind come out of testng.
 
Method Summary
 void addInvokedMethodListener(IInvokedMethodListener listener)
           
 void addListener(IInvokedMethodListener listener)
           
 void addListener(IReporter listener)
           
 void addListener(ISuiteListener listener)
           
 void addListener(ITestListener listener)
           
 void addListener(java.lang.Object listener)
           
 void addMethodSelector(java.lang.String className, int priority)
           
protected static java.util.Map checkConditions(java.util.Map params)
          Checks TestNG preconditions.
 void configure(java.util.Map cmdLineArgs)
          Configure the TestNG instance by reading the settings provided in the map.
protected  SuiteRunner createAndRunSuiteRunners(XmlSuite xmlSuite)
           
 IAnnotationTransformer getAnnotationTransformer()
           
static TestNG getDefault()
          Deprecated. since 5.1
 java.lang.String getDefaultSuiteName()
           
 java.lang.String getDefaultTestName()
           
 java.lang.String getOutputDirectory()
           
 java.util.List<IReporter> getReporters()
           
 boolean getSkipFailedInvocationCounts()
           
 int getStatus()
           
 java.util.List<ISuiteListener> getSuiteListeners()
           
 java.util.List<ITestListener> getTestListeners()
           
 boolean hasFailure()
           
 boolean hasFailureWithinSuccessPercentage()
           
 boolean hasSkip()
           
 void initializeSuitesAndJarFile()
           
static boolean isJdk14()
          Returns true if this is the JDK 1.4 JAR version of TestNG, false otherwise.
static void main(java.lang.String[] argv)
          The TestNG entry point for command line execution.
static TestNG privateMain(java.lang.String[] argv, ITestListener listener)
           
 void run()
          Run TestNG.
 java.util.List<ISuite> runSuitesLocally()
          This needs to be public for maven2, for now..At least until an alternative mechanism is found.
 void setAnnotations(java.lang.String annotationType)
          Sets the default annotation type for suites that have not explicitly set the annotation property.
 void setAnnotationTransformer(IAnnotationTransformer t)
           
 void setCommandLineSuite(XmlSuite suite)
           
 void setDataProviderThreadCount(int count)
           
 void setDefaultSuiteName(java.lang.String defaultSuiteName)
           
 void setDefaultTestName(java.lang.String defaultTestName)
           
 void setExcludedGroups(java.lang.String groups)
          Define which groups will be excluded from this run.
 void setGroups(java.lang.String groups)
          Define which groups will be included from this run.
 void setHasFailure(boolean hasFailure)
          Deprecated. since 5.1
 void setHasFailureWithinSuccessPercentage(boolean hasFailureWithinSuccessPercentage)
          Deprecated. since 5.1
 void setHasSkip(boolean hasSkip)
          Deprecated. since 5.1
 void setJUnit(java.lang.Boolean isJUnit)
          Specify if this run should be made in JUnit mode
 void setListenerClasses(java.util.List<java.lang.Class> classes)
          Define which listeners to user for this run.
 void setMaster(java.lang.String fileName)
          Specify if this run should be in Master-Slave mode as Master
 void setMethodInterceptor(IMethodInterceptor methodInterceptor)
           
 void setObjectFactory(java.lang.Class c)
           
 void setOutputDirectory(java.lang.String outputdir)
          Sets the output directory where the reports will be created.
 void setParallel(java.lang.String parallel)
          Define whether this run will be run in parallel mode.
 void setSkipFailedInvocationCounts(boolean skip)
           
 void setSlave(java.lang.String fileName)
          Specify if this run should be in Master-Slave mode as slave
 void setSourcePath(java.lang.String sourcePaths)
          Sets the ; separated path of source directories.
protected  void setStatus(int status)
           
 void setTarget(java.lang.String target)
          Deprecated. use the setDefaultAnnotationType replacement method.
 void setTestClasses(java.lang.Class[] classes)
          Set the test classes to be run by this TestNG object.
 void setTestJar(java.lang.String jarPath)
          Sets a jar containing a testng.xml file.
static void setTestNGVersion()
          Deprecated. The TestNG version is now established at load time. This method is not required anymore and is now a no-op.
protected  void setTestRunnerFactory(ITestRunnerFactory itrf)
           
protected  void setTestRunnerFactoryClass(java.lang.Class testRunnerFactoryClass)
           
 void setTestSuites(java.util.List<java.lang.String> suites)
          Set the suites file names to be run by this TestNG object.
 void setThreadCount(int threadCount)
          Define the number of threads in the thread pool.
 void setUseDefaultListeners(boolean useDefaultListeners)
          If this method is passed true before run(), the default listeners will not be used.
 void setVerbose(int verbose)
          Sets the level of verbosity.
 void setXmlSuites(java.util.List<XmlSuite> suites)
          Specifies the XmlSuite objects to run.
static void usage()
          Prints the usage message to System.out.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_COMMAND_LINE_SUITE_NAME

public static final java.lang.String DEFAULT_COMMAND_LINE_SUITE_NAME
The default name for a suite launched from the command line

See Also:
Constant Field Values

DEFAULT_COMMAND_LINE_TEST_NAME

public static final java.lang.String DEFAULT_COMMAND_LINE_TEST_NAME
The default name for a test launched from the command line

See Also:
Constant Field Values

DEFAULT_OUTPUTDIR

public static final java.lang.String DEFAULT_OUTPUTDIR
The default name of the result's output directory.

See Also:
Constant Field Values

SRC_SEPARATOR

public static final java.lang.String SRC_SEPARATOR
A separator constant (semi-colon).

See Also:
Constant Field Values

JDK_ANNOTATION_TYPE

public static final java.lang.String JDK_ANNOTATION_TYPE
The JDK50 annotation type ID ("JDK5").


JAVADOC_ANNOTATION_TYPE

public static final java.lang.String JAVADOC_ANNOTATION_TYPE
The JavaDoc annotation type ID ("javadoc").


m_suites

protected java.util.List<XmlSuite> m_suites

m_cmdlineSuites

protected java.util.List<XmlSuite> m_cmdlineSuites

m_outputDir

protected java.lang.String m_outputDir

m_sourceDirs

protected java.lang.String[] m_sourceDirs
The source directories as set by setSourcePath (or testng-sourcedir-override.properties).


m_javadocAnnotationFinder

protected IAnnotationFinder m_javadocAnnotationFinder

m_jdkAnnotationFinder

protected IAnnotationFinder m_jdkAnnotationFinder

m_includedGroups

protected java.lang.String[] m_includedGroups

m_excludedGroups

protected java.lang.String[] m_excludedGroups

m_useDefaultListeners

protected boolean m_useDefaultListeners

m_testRunnerFactory

protected ITestRunnerFactory m_testRunnerFactory

m_testListeners

protected java.util.List<ITestListener> m_testListeners

m_suiteListeners

protected java.util.List<ISuiteListener> m_suiteListeners

HAS_FAILURE

public static final int HAS_FAILURE
See Also:
Constant Field Values

HAS_SKIPPED

public static final int HAS_SKIPPED
See Also:
Constant Field Values

HAS_FSP

public static final int HAS_FSP
See Also:
Constant Field Values

HAS_NO_TEST

public static final int HAS_NO_TEST
See Also:
Constant Field Values

m_status

protected int m_status

m_hasTests

protected boolean m_hasTests

m_invokedMethodListeners

protected java.util.List<IInvokedMethodListener> m_invokedMethodListeners
Constructor Detail

TestNG

public TestNG()
Default constructor. Setting also usage of default listeners/reporters.


TestNG

public TestNG(boolean useDefaultListeners)
Used by maven2 to have 0 output of any kind come out of testng.

Parameters:
useDefaultListeners - Whether or not any default reports should be added to tests.
Method Detail

getStatus

public int getStatus()

setStatus

protected void setStatus(int status)

setOutputDirectory

public void setOutputDirectory(java.lang.String outputdir)
Sets the output directory where the reports will be created.

Parameters:
outputdir - The directory.

setUseDefaultListeners

public void setUseDefaultListeners(boolean useDefaultListeners)
If this method is passed true before run(), the default listeners will not be used.

See Also:
org.testng.reporters.TestHTMLReporter, org.testng.reporters.JUnitXMLReporter, org.testng.reporters.XMLReporter

setTarget

@Deprecated
public void setTarget(java.lang.String target)
Deprecated. use the setDefaultAnnotationType replacement method.

Sets the default annotation type for suites that have not explicitly set the annotation property. The target is used only in JDK5+.

Parameters:
target - the default annotation type. This is one of the two constants (TestNG.JAVADOC_ANNOTATION_TYPE or TestNG.JDK_ANNOTATION_TYPE). For backward compatibility reasons we accept "1.4", "1.5". Any other value will default to TestNG.JDK_ANNOTATION_TYPE.

setAnnotations

public void setAnnotations(java.lang.String annotationType)
Sets the default annotation type for suites that have not explicitly set the annotation property. The target is used only in JDK5+.

Parameters:
annotationType - the default annotation type. This is one of the two constants (TestNG.JAVADOC_ANNOTATION_TYPE or TestNG.JDK_ANNOTATION_TYPE). For backward compatibility reasons we accept "1.4", "1.5". Any other value will default to TestNG.JDK_ANNOTATION_TYPE.

setSourcePath

public void setSourcePath(java.lang.String sourcePaths)
Sets the ; separated path of source directories. This is used only with JavaDoc type annotations. The directories do not have to be the root of a class hierarchy. For example, "c:\java\src\org\testng" is a valid directory. If a resource named "testng-sourcedir-override.properties" is found in the classpath, it will override this call. "testng-sourcedir-override.properties" must contain a sourcedir property initialized with a semi-colon list of directories. For example: sourcedir=c:\java\src\org\testng;D:/dir2 Considering the syntax of a properties file, you must escape the usage of : and = in your paths. Note that for the override to occur, this method must be called. i.e. it is not sufficient to place "testng-sourcedir-override.properties" in the classpath.

Parameters:
sourcePaths - a semi-colon separated list of source directories.

setTestJar

public void setTestJar(java.lang.String jarPath)
Sets a jar containing a testng.xml file.

Parameters:
jarPath -

initializeSuitesAndJarFile

public void initializeSuitesAndJarFile()

setThreadCount

public void setThreadCount(int threadCount)
Define the number of threads in the thread pool.


setParallel

public void setParallel(java.lang.String parallel)
Define whether this run will be run in parallel mode.


setCommandLineSuite

public void setCommandLineSuite(XmlSuite suite)

setTestClasses

public void setTestClasses(java.lang.Class[] classes)
Set the test classes to be run by this TestNG object. This method will create a dummy suite that will wrap these classes called "Command Line Test".

If used together with threadCount, parallel, groups, excludedGroups than this one must be set first.

Parameters:
classes - An array of classes that contain TestNG annotations.

addMethodSelector

public void addMethodSelector(java.lang.String className,
                              int priority)

setTestSuites

public void setTestSuites(java.util.List<java.lang.String> suites)
Set the suites file names to be run by this TestNG object. This method tries to load and parse the specified TestNG suite xml files. If a file is missing, it is ignored.

Parameters:
suites - A list of paths to one more XML files defining the tests. For example:
 TestNG tng = new TestNG();
 List suites = new ArrayList();
 suites.add("c:/tests/testng1.xml");
 suites.add("c:/tests/testng2.xml");
 tng.setTestSuites(suites);
 tng.run();
 

setXmlSuites

public void setXmlSuites(java.util.List<XmlSuite> suites)
Specifies the XmlSuite objects to run.

Parameters:
suites -
See Also:
XmlSuite

setExcludedGroups

public void setExcludedGroups(java.lang.String groups)
Define which groups will be excluded from this run.

Parameters:
groups - A list of group names separated by a comma.

setGroups

public void setGroups(java.lang.String groups)
Define which groups will be included from this run.

Parameters:
groups - A list of group names separated by a comma.

setTestRunnerFactoryClass

protected void setTestRunnerFactoryClass(java.lang.Class testRunnerFactoryClass)

setTestRunnerFactory

protected void setTestRunnerFactory(ITestRunnerFactory itrf)

setObjectFactory

public void setObjectFactory(java.lang.Class c)

setListenerClasses

public void setListenerClasses(java.util.List<java.lang.Class> classes)
Define which listeners to user for this run.

Parameters:
classes - A list of classes, which must be either ISuiteListener, ITestListener or IReporter

addListener

public void addListener(java.lang.Object listener)

addListener

public void addListener(IInvokedMethodListener listener)

addListener

public void addListener(ISuiteListener listener)

addListener

public void addListener(ITestListener listener)

addListener

public void addListener(IReporter listener)

addInvokedMethodListener

public void addInvokedMethodListener(IInvokedMethodListener listener)

getReporters

public java.util.List<IReporter> getReporters()

getTestListeners

public java.util.List<ITestListener> getTestListeners()

getSuiteListeners

public java.util.List<ISuiteListener> getSuiteListeners()

setVerbose

public void setVerbose(int verbose)
Sets the level of verbosity. This value will override the value specified in the test suites.

Parameters:
verbose - the verbosity level (0 to 10 where 10 is most detailed) Actually, this is a lie: you can specify -1 and this will put TestNG in debug mode (no longer slicing off stack traces and all).

run

public void run()
Run TestNG.


runSuitesLocally

public java.util.List<ISuite> runSuitesLocally()
This needs to be public for maven2, for now..At least until an alternative mechanism is found.

Returns:

createAndRunSuiteRunners

protected SuiteRunner createAndRunSuiteRunners(XmlSuite xmlSuite)

main

public static void main(java.lang.String[] argv)
The TestNG entry point for command line execution.

Parameters:
argv - the TestNG command line parameters.

privateMain

public static TestNG privateMain(java.lang.String[] argv,
                                 ITestListener listener)
Parameters:
argv -
listener -
Returns:

configure

public void configure(java.util.Map cmdLineArgs)
Configure the TestNG instance by reading the settings provided in the map.

Parameters:
cmdLineArgs - map of settings
See Also:
for setting keys

setMaster

public void setMaster(java.lang.String fileName)
Specify if this run should be in Master-Slave mode as Master

Parameters:
fileName - remote.properties path

setSlave

public void setSlave(java.lang.String fileName)
Specify if this run should be in Master-Slave mode as slave

Parameters:
fileName - remote.properties path

setJUnit

public void setJUnit(java.lang.Boolean isJUnit)
Specify if this run should be made in JUnit mode

Parameters:
isJUnit -

setTestNGVersion

@Deprecated
public static void setTestNGVersion()
Deprecated. The TestNG version is now established at load time. This method is not required anymore and is now a no-op.


isJdk14

public static boolean isJdk14()
Returns true if this is the JDK 1.4 JAR version of TestNG, false otherwise.

Returns:
true if this is the JDK 1.4 JAR version of TestNG, false otherwise.

checkConditions

protected static java.util.Map checkConditions(java.util.Map params)
Checks TestNG preconditions. For example, this method makes sure that if this is the JDK 1.4 version of TestNG, a source directory has been specified. This method calls System.exit(-1) or throws an exception if the preconditions are not satisfied.

Parameters:
params - the parsed command line parameters.

hasFailure

public boolean hasFailure()
Returns:
true if at least one test failed.

hasFailureWithinSuccessPercentage

public boolean hasFailureWithinSuccessPercentage()
Returns:
true if at least one test failed within success percentage.

hasSkip

public boolean hasSkip()
Returns:
true if at least one test was skipped.

usage

public static void usage()
Prints the usage message to System.out. This message describes all the command line options.


getOutputDirectory

public java.lang.String getOutputDirectory()

getAnnotationTransformer

public IAnnotationTransformer getAnnotationTransformer()

getSkipFailedInvocationCounts

public boolean getSkipFailedInvocationCounts()

setSkipFailedInvocationCounts

public void setSkipFailedInvocationCounts(boolean skip)

setAnnotationTransformer

public void setAnnotationTransformer(IAnnotationTransformer t)

getDefaultSuiteName

public java.lang.String getDefaultSuiteName()
Returns:
the defaultSuiteName

setDefaultSuiteName

public void setDefaultSuiteName(java.lang.String defaultSuiteName)
Parameters:
defaultSuiteName - the defaultSuiteName to set

getDefaultTestName

public java.lang.String getDefaultTestName()
Returns:
the defaultTestName

setDefaultTestName

public void setDefaultTestName(java.lang.String defaultTestName)
Parameters:
defaultTestName - the defaultTestName to set

getDefault

@Deprecated
public static TestNG getDefault()
Deprecated. since 5.1


setHasFailure

@Deprecated
public void setHasFailure(boolean hasFailure)
Deprecated. since 5.1


setHasFailureWithinSuccessPercentage

@Deprecated
public void setHasFailureWithinSuccessPercentage(boolean hasFailureWithinSuccessPercentage)
Deprecated. since 5.1


setHasSkip

@Deprecated
public void setHasSkip(boolean hasSkip)
Deprecated. since 5.1


setMethodInterceptor

public void setMethodInterceptor(IMethodInterceptor methodInterceptor)

setDataProviderThreadCount

public void setDataProviderThreadCount(int count)