org.netbeans.junit

Class NbTestCase

java.lang.Object

junit.framework.Assert

junit.framework.TestCase

org.netbeans.junit.NbTestCase

All Implemented Interfaces:

junit.framework.Test, NbTest

Direct Known Subclasses:

MultiTestCase, NbPerformanceTestCase

public abstract class NbTestCase
extends junit.framework.TestCase
implements NbTest

NetBeans extension to JUnit's TestCase. Adds various abilities such as comparing golden files, getting a working directory for test files, testing memory usage, etc.

Constructor Summary

Constructors

Constructor and Description
NbTestCase(String name) Constructs a test case with the given name.

Method Summary

Methods

Modifier and Type	Method and Description
static void	assertFile(File test, File pass) Asserts that two files are the same, it just compares two files and doesn't produce any additional output.
static void	assertFile(File test, File pass, File diff) Asserts that two files are the same, it compares two files and stores possible differences in the output file.
static void	assertFile(File test, File pass, File diff, Diff externalDiff) Asserts that two files are the same, it uses specific Diff implementation to compare two files and stores possible differences in the output file.
static void	assertFile(String message, File test, File pass, File diff) Asserts that two files are the same, it compares two files and stores possible differences in the output file, the message is displayed when assertion fails.
static void	assertFile(String message, File test, File pass, File diff, Diff externalDiff) Asserts that two files are the same (their content is identical), when files differ AssertionFileFailedError exception is thrown.
static void	assertFile(String test, String pass) Asserts that two files are the same, it just compares two files and doesn't produce any additional output.
static void	assertFile(String test, String pass, String diff) Asserts that two files are the same, it compares two files and stores possible differences in the output file.
static void	assertFile(String test, String pass, String diff, Diff externalDiff) Asserts that two files are the same, it uses specific Diff implementation to compare two files and stores possible differences in the output file.
static void	assertFile(String message, String test, String pass, String diff) Asserts that two files are the same, it compares two files and stores possible differences in the output file, the message is displayed when assertion fails.
static void	assertFile(String message, String test, String pass, String diff, Diff externalDiff) Asserts that two files are the same (their content is identical), when files differ AssertionFileFailedError exception is thrown.
static void	assertGC(String text, Reference<?> ref) Asserts that the object can be garbage collected.
static void	assertGC(String text, Reference<?> ref, Set<?> rootsHint) Asserts that the object can be garbage collected.
static void	assertSize(String message, Collection<?> roots, int limit) Assert size of some structure.
static int	assertSize(String message, Collection<?> roots, int limit, MemoryFilter skip) Assert size of some structure.
static void	assertSize(String message, Collection<?> roots, int limit, Object[] skip) Assert size of some structure.
static void	assertSize(String message, int limit, Object root) Assert size of some structure.
boolean	canRun() Checks if a test isn't filtered out by the active filter.
void	clearWorkDir() Deletes all files including subdirectories in test's working directory.
void	compareReferenceFiles() Compares default golden file and default reference log.
void	compareReferenceFiles(String testFilename, String goldenFilename, String diffFilename) Compares golden file and reference log.
static String	convertNBFSURL(URL url) Deprecated. No longer applicable as of NB 4.0 at the latest. FileObject.getURL() should be returning a file-protocol URL, which can be converted to a disk path using new File(URI); or use FileUtil.toFile.
static void	failByBug(int bugID) Fails a test with known bug ID.
static void	failByBug(int bugID, String message) Fails a test with known bug ID and with the given message.
File	getDataDir() Returns pointer to directory with test data (golden files, sample files, ...).
String	getExpectedFail() Returns expected fail message.
File	getGoldenFile() Get the default testmethod specific golden file from data/goldenfiles/${classname}/${testmethodname}.pass
File	getGoldenFile(String filename) Get the test method specific golden file from ${xtest.data}/goldenfiles/${classname} directory.
PrintStream	getLog() Return default log named as ${testmethod}.log.
PrintStream	getLog(String logName) Returns named log stream.
PrintStream	getRef() Get PrintStream to log inteded for reference files comparision.
protected int	getTestNumber() Parses the test name to find out whether it encodes a number.
File	getWorkDir() Returns unique working directory for a test (each test method has a unique dir).
String	getWorkDirPath() Returns path to test method working directory as a String.
void	log(String message) Simple and easy to use method for printing a message to a default log
void	log(String log, String message) Easy to use method for logging a message to a named log
protected Level	logLevel() Allows easy collecting of log messages send thru java.util.logging API.
protected String	logRoot() If overriding logLevel(), may override this as well to collect messages from only some code.
void	ref(String message) Easy to use logging method for printing a message to a reference log.
void	run(junit.framework.TestResult result) Runs the test case, while conditionally skip some according to result of canRun() method.
void	runBare() Runs the bare test sequence.
protected boolean	runInEQ() Provide ability for tests, setUp and tearDown to request that they run only in the AWT event queue.
void	setFilter(Filter filter) Sets active filter.
protected int	timeOut() Provides support for tests that can have problems with terminating.

Methods inherited from class junit.framework.TestCase

countTestCases, createResult, getName, run, runTest, setName, setUp, tearDown, toString

Methods inherited from class junit.framework.Assert

assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotNull, assertNotNull, assertNotSame, assertNotSame, assertNull, assertNull, assertSame, assertSame, assertTrue, assertTrue, fail, fail, failNotEquals, failNotSame, failSame, format

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface junit.framework.Test

countTestCases

Constructor Detail

NbTestCase

public NbTestCase(String name)

Constructs a test case with the given name. Normally you will just use:

 public class MyTest extends NbTestCase {
     public MyTest(String name) {super(name);}
     public void testWhatever() {...}
 }
 

Parameters:

name - name of the test case

Method Detail

setFilter

public void setFilter(Filter filter)

Sets active filter.

Specified by:

setFilter in interface NbTest

Parameters:

filter - Filter to be set as active for current test, null will reset filtering.

getExpectedFail

public String getExpectedFail()

Returns expected fail message.

Specified by:

getExpectedFail in interface NbTest

Returns:

expected fail message if it's expected this test fail, null otherwise.

canRun

public boolean canRun()

Checks if a test isn't filtered out by the active filter.

Specified by:

canRun in interface NbTest

Returns:

true if the test can run

runInEQ

protected boolean runInEQ()

Provide ability for tests, setUp and tearDown to request that they run only in the AWT event queue. By default, false.

Returns:

true to run all test methods, setUp and tearDown in the EQ, false to run in whatever thread

timeOut

protected int timeOut()

Provides support for tests that can have problems with terminating. Runs the test in a "watchdog" that measures the time the test shall take and if it does not terminate it reports a failure including a thread dump.

If the system property nbjunit.hard.timeout is set to a number (of milliseconds) by which the whole VM must exit (as in the timeout property to Ant's <junit> task), this "soft timeout" will default to some portion of the remaining time, so that we can capture a meaningful thread dump rather than simply report that the test took too long. (If the VM crashes, the hard timeout kicks in.) Otherwise the default is 0 (no soft timeout). For an Ant-based NBM project, common.xml specifies 600000 (ten minutes) as a default hard timeout, and sets the system property, so soft timeouts should be the default.

Returns:

amount ms to give one test to finish or 0 to disable time outs

Since:

1.20

logLevel

protected Level logLevel()

Allows easy collecting of log messages send thru java.util.logging API. Overwrite and return the log level to collect logs to logging file. If the method returns non-null level, then the level is assigned to the Logger.getLogger(logRoot()) and the messages reported to it are then send into regular log file (which is accessible thru getLog(java.lang.String)) and in case of failure the last few messages is also included in failure.getMessage().

Returns:

default implementation returns null which disables any logging support in test

Since:

1.27

See Also:

Log.enable(java.lang.String, java.util.logging.Level)

logRoot

protected String logRoot()

If overriding logLevel(), may override this as well to collect messages from only some code.

Returns:

"" (default) to collect messages from all loggers; or "my.pkg" or "my.pkg.Class" etc.

Since:

1.68

run

public void run(junit.framework.TestResult result)

Runs the test case, while conditionally skip some according to result of canRun() method.

Specified by:

run in interface junit.framework.Test

Overrides:

run in class junit.framework.TestCase

runBare

public void runBare()
             throws Throwable

Runs the bare test sequence. It checks runInEQ() and possibly schedules the call of setUp, runTest and tearDown to AWT event thread. It also consults timeOut() and if so, it starts a count down and aborts the runTest if the time out expires.

Overrides:

runBare in class junit.framework.TestCase

Throws:

Throwable - if any exception is thrown

getTestNumber

protected final int getTestNumber()

Parses the test name to find out whether it encodes a number. The testSomeName1343 represents number 1343.

Returns:

the number

Throws:

may - throw AssertionFailedError if the number is not found in the test name

assertFile

public static void assertFile(String message,
              String test,
              String pass,
              String diff,
              Diff externalDiff)

Asserts that two files are the same (their content is identical), when files differ AssertionFileFailedError exception is thrown. Depending on the Diff implementation additional output can be generated to the file/dir specified by the diff param.

Parameters:

message - the detail message for this assertion

test - first file to be compared, by the convention this should be the test-generated file

pass - second file to be compared, it should be so called 'golden' file, which defines the correct content for the test-generated file.

diff - file, where differences will be stored, when null differences will not be stored. In case it points to directory the result file name is constructed from the pass argument and placed to that directory. Constructed file name consists from the name of pass file (without extension and path) appended by the '.diff'.

externalDiff - instance of class implementing the Diff interface, it has to be already initialized, when passed in this assertFile function.

assertFile

public static void assertFile(String test,
              String pass,
              String diff,
              Diff externalDiff)

Asserts that two files are the same, it uses specific Diff implementation to compare two files and stores possible differences in the output file.

Parameters:

test - first file to be compared, by the convention this should be the test-generated file

pass - second file to be compared, it should be so called 'golden' file, which defines the correct content for the test-generated file.

diff - file, where differences will be stored, when null differences will not be stored. In case it points to directory the result file name is constructed from the pass argument and placed to that directory. Constructed file name consists from the name of pass file (without extension and path) appended by the '.diff'.

externalDiff - instance of class implementing the Diff interface, it has to be already initialized, when passed in this assertFile function.

assertFile

public static void assertFile(String message,
              String test,
              String pass,
              String diff)

Asserts that two files are the same, it compares two files and stores possible differences in the output file, the message is displayed when assertion fails.

Parameters:

message - the detail message for this assertion

test - first file to be compared, by the convention this should be the test-generated file

pass - second file to be compared, it should be so called 'golden' file, which defines the correct content for the test-generated file.

diff - file, where differences will be stored, when null differences will not be stored. In case it points to directory the result file name is constructed from the pass argument and placed to that directory. Constructed file name consists from the name of pass file (without extension and path) appended by the '.diff'.

assertFile

public static void assertFile(String test,
              String pass,
              String diff)

Asserts that two files are the same, it compares two files and stores possible differences in the output file.

Parameters:

test - first file to be compared, by the convention this should be the test-generated file

pass - second file to be compared, it should be so called 'golden' file, which defines the correct content for the test-generated file.

diff - file, where differences will be stored, when null differences will not be stored. In case it points to directory the result file name is constructed from the pass argument and placed to that directory. Constructed file name consists from the name of pass file (without extension and path) appended by the '.diff'.

assertFile

public static void assertFile(String test,
              String pass)

Asserts that two files are the same, it just compares two files and doesn't produce any additional output.

Parameters:

test - first file to be compared, by the convention this should be the test-generated file

pass - second file to be compared, it should be so called 'golden' file, which defines the correct content for the test-generated file.

assertFile

public static void assertFile(String message,
              File test,
              File pass,
              File diff,
              Diff externalDiff)

Asserts that two files are the same (their content is identical), when files differ AssertionFileFailedError exception is thrown. Depending on the Diff implementation additional output can be generated to the file/dir specified by the diff param.

Parameters:

message - the detail message for this assertion

test - first file to be compared, by the convention this should be the test-generated file

pass - second file to be compared, it should be so called 'golden' file, which defines the correct content for the test-generated file.

diff - file, where differences will be stored, when null differences will not be stored. In case it points to directory the result file name is constructed from the pass argument and placed to that directory. Constructed file name consists from the name of pass file (without extension and path) appended by the '.diff'.

externalDiff - instance of class implementing the Diff interface, it has to be already initialized, when passed in this assertFile function.

assertFile

public static void assertFile(File test,
              File pass,
              File diff,
              Diff externalDiff)

Asserts that two files are the same, it uses specific Diff implementation to compare two files and stores possible differences in the output file.

Parameters:

test - first file to be compared, by the convention this should be the test-generated file

pass - second file to be compared, it should be so called 'golden' file, which defines the correct content for the test-generated file.

diff - file, where differences will be stored, when null differences will not be stored. In case it points to directory the result file name is constructed from the pass argument and placed to that directory. Constructed file name consists from the name of pass file (without extension and path) appended by the '.diff'.

externalDiff - instance of class implementing the Diff interface, it has to be already initialized, when passed in this assertFile function.

assertFile

public static void assertFile(String message,
              File test,
              File pass,
              File diff)

Asserts that two files are the same, it compares two files and stores possible differences in the output file, the message is displayed when assertion fails.

Parameters:

message - the detail message for this assertion

test - first file to be compared, by the convention this should be the test-generated file

pass - second file to be compared, it should be so called 'golden' file, which defines the correct content for the test-generated file.

diff - file, where differences will be stored, when null differences will not be stored. In case it points to directory the result file name is constructed from the pass argument and placed to that directory. Constructed file name consists from the name of pass file (without extension and path) appended by the '.diff'.

assertFile

public static void assertFile(File test,
              File pass,
              File diff)

Asserts that two files are the same, it compares two files and stores possible differences in the output file.

Parameters:

test - first file to be compared, by the convention this should be the test-generated file

pass - second file to be compared, it should be so called 'golden' file, which defines the correct content for the test-generated file.

diff - file, where differences will be stored, when null differences will not be stored. In case it points to directory the result file name is constructed from the pass argument and placed to that directory. Constructed file name consists from the name of pass file (without extension and path) appended by the '.diff'.

assertFile

public static void assertFile(File test,
              File pass)

Asserts that two files are the same, it just compares two files and doesn't produce any additional output.

Parameters:

test - first file to be compared, by the convention this should be the test-generated file

pass - second file to be compared, it should be so called 'golden' file, which defines the correct content for the test-generated file.

getWorkDirPath

public String getWorkDirPath()

Returns path to test method working directory as a String. Path is constructed as ${nbjunit.workdir}/${package}.${classname}/${testmethodname}. (The nbjunit.workdir property should be set in junit.properties; otherwise the default is ${java.io.tmpdir}/tests.) Please note that this method does not guarantee that the working directory really exists.

Returns:

a path to a test method working directory

getWorkDir

public File getWorkDir()
                throws IOException

Returns unique working directory for a test (each test method has a unique dir). If not available, method tries to create it. This method uses getWorkDirPath() method to determine the unique path.

Warning: the working directory is not guaranteed to be empty when you get it, so if this is being called in TestCase.setUp() you are strongly advised to first call clearWorkDir() to ensure that each test run starts with a clean slate.

Returns:

file to the working directory directory

Throws:

IOException - if the directory cannot be created

clearWorkDir

public void clearWorkDir()
                  throws IOException

Deletes all files including subdirectories in test's working directory.

Throws:

IOException - if any problem has occured during deleting files/directories

getLog

public PrintStream getLog(String logName)

Returns named log stream. If log cannot be created as a file in the testmethod working directory, PrintStream created from System.out is used. Please note, that tests shoudn't call log.close() method, unless they really don't want to use this log anymore.

Parameters:

logName - name of the log - file in the working directory

Returns:

Log PrintStream

getLog

public PrintStream getLog()

Return default log named as ${testmethod}.log. If the log cannot be created as a file in testmethod working directory, PrinterStream to System.out is returned

Returns:

log

log

public void log(String message)

Simple and easy to use method for printing a message to a default log

Parameters:

message - meesage to log

log

public void log(String log,
       String message)

Easy to use method for logging a message to a named log

Parameters:

log - which log to use

message - message to log

getRef

public PrintStream getRef()

Get PrintStream to log inteded for reference files comparision. Reference log is stored as a file named ${testmethod}.ref in test method working directory. If the file cannot be created, the testcase will automatically fail.

Returns:

PrintStream to referencing log

ref

public void ref(String message)

Easy to use logging method for printing a message to a reference log.

Parameters:

message - message to log

getGoldenFile

public File getGoldenFile(String filename)

Get the test method specific golden file from ${xtest.data}/goldenfiles/${classname} directory. If not found, try also deprecated src/data/goldenfiles/${classname} resource directory.

Parameters:

filename - filename to get from golden files directory

Returns:

golden file

getDataDir

public File getDataDir()

Returns pointer to directory with test data (golden files, sample files, ...). It is the same from xtest.data property.

Returns:

data directory

getGoldenFile

public File getGoldenFile()

Get the default testmethod specific golden file from data/goldenfiles/${classname}/${testmethodname}.pass

Returns:

filename to get from golden files resource directory

compareReferenceFiles

public void compareReferenceFiles(String testFilename,
                         String goldenFilename,
                         String diffFilename)

Compares golden file and reference log. If both files are the same, test passes. If files differ, test fails and diff file is created (diff is created only when using native diff, for details see JUnit module documentation)

Parameters:

testFilename - reference log file name

goldenFilename - golden file name

diffFilename - diff file name (optional, if null, then no diff is created)

compareReferenceFiles

public void compareReferenceFiles()

Compares default golden file and default reference log. If both files are the same, test passes. If files differ, test fails and default diff (${methodname}.diff) file is created (diff is created only when using native diff, for details see JUnit module documentation)

convertNBFSURL

@Deprecated
public static String convertNBFSURL(URL url)

Deprecated. No longer applicable as of NB 4.0 at the latest. FileObject.getURL() should be returning a file-protocol URL, which can be converted to a disk path using new File(URI); or use FileUtil.toFile.

Converts NetBeans filesystem URL to absolute path.

Parameters:

url - URL to convert

Returns:

absolute path

assertGC

public static void assertGC(String text,
            Reference<?> ref)

Asserts that the object can be garbage collected. Tries to GC ref's referent.

Parameters:

text - the text to show when test fails.

ref - the referent to object that should be GCed

assertGC

public static void assertGC(String text,
            Reference<?> ref,
            Set<?> rootsHint)

Asserts that the object can be garbage collected. Tries to GC ref's referent.

Parameters:

text - the text to show when test fails.

ref - the referent to object that should be GCed

rootsHint - a set of objects that should be considered part of the rootset for this scan. This is useful if you want to verify that one structure (usually long living in real application) is not holding another structure in memory, without setting a static reference to the former structure.

Example:

  // test body
  WeakHashMap map = new WeakHashMap();
  Object target = new Object();
  map.put(target, "Val");
  
  // verification step
  Reference ref = new WeakReference(target);
  target = null;
  assertGC("WeakMap does not hold the key", ref, Collections.singleton(map));
 

assertSize

public static void assertSize(String message,
              int limit,
              Object root)

Assert size of some structure. Traverses the whole reference graph of objects accessible from given root object and check its size against the limit.

Parameters:

message - the text to show when test fails.

limit - maximal allowed heap size of the structure

root - the root object from which to traverse

assertSize

public static void assertSize(String message,
              Collection<?> roots,
              int limit)

Assert size of some structure. Traverses the whole reference graph of objects accessible from given roots and check its size against the limit.

Parameters:

message - the text to show when test fails.

roots - the collection of root objects from which to traverse

limit - maximal allowed heap size of the structure

assertSize

public static void assertSize(String message,
              Collection<?> roots,
              int limit,
              Object[] skip)

Assert size of some structure. Traverses the whole reference graph of objects accessible from given roots and check its size against the limit.

Parameters:

message - the text to show when test fails.

roots - the collection of root objects from which to traverse

limit - maximal allowed heap size of the structure

skip - Array of objects used as a boundary during heap scanning, neither these objects nor references from these objects are counted.

assertSize

public static int assertSize(String message,
             Collection<?> roots,
             int limit,
             MemoryFilter skip)

Assert size of some structure. Traverses the whole reference graph of objects accessible from given roots and check its size against the limit.

Parameters:

message - the text to show when test fails.

roots - the collection of root objects from which to traverse

limit - maximal allowed heap size of the structure

skip - custom filter for counted objects

Returns:

actual size or -1 on internal error.

failByBug

public static void failByBug(int bugID)

Fails a test with known bug ID.

Parameters:

bugID - the bug number according bug report system.

failByBug

public static void failByBug(int bugID,
             String message)

Fails a test with known bug ID and with the given message.

Parameters:

bugID - the bug number according bug report system.

message - the text to show when test fails.