org.eclipse.ease.lang.unittest

## Class UnitTestModule

- java.lang.Object
- - org.eclipse.ease.modules.AbstractScriptModule
  - - org.eclipse.ease.lang.unittest.UnitTestModule

All Implemented Interfaces:
  IScriptModule

    public class UnitTestModule
    extends AbstractScriptModule

Support methods for scripted unit tests. Provides several assertion methods and utility functions to manipulate the current test instances and states.

### Constructor Summary

Constructors
Constructor and Description
`UnitTestModule()`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`void` `addMetaData(java.lang.String name, java.lang.Object value)` Append generic data to the current test, testfile or test suite.
`ITestContainer` `addTestClass(java.lang.String className)`
`static IAssertion` `assertEquals(java.lang.Object expected, java.lang.Object actual, java.lang.Object errorDescription)` Expect two objects to be equal.
`static IAssertion` `assertFalse(java.lang.Boolean actual, java.lang.Object errorDescription)` Asserts when provided value is `true`.
`void` `assertion(IAssertion reason)` Create a new assertion for the current test.
`static IAssertion` `assertMatch(java.lang.String pattern, java.lang.String candidate, java.lang.String errorMessage)` Asserts when provided value does not match to a given regular expression pattern.
`static IAssertion` `assertNotEquals(java.lang.Object expected, java.lang.Object actual, java.lang.Object errorDescription)` Expect two objects not to be equal.
`static IAssertion` `assertNotNull(java.lang.Object actual, java.lang.Object errorDescription)` Asserts when provided value is `null`.
`static IAssertion` `assertNull(java.lang.Object actual, java.lang.Object errorDescription)` Asserts when provided value is not `null`.
`static IAssertion` `assertTrue(java.lang.Boolean actual, java.lang.Object errorDescription)` Asserts when provided value is `false`.
`void` `createReport(java.lang.String reportType, ITestEntity suite, java.lang.Object fileLocation, java.lang.String title, java.lang.String description, java.lang.Object reportData)` Create a test report file.
`void` `endTest()` End the current test.
`void` `error(java.lang.String message)` Force an error for the current test entity (test/testclass/testfile/testsuite).
`void` `error(java.lang.String message, ScriptStackTrace stackTrace)` Called from the javascript runner.
`java.lang.Object` `executeUserCode(java.lang.String location)` Execute code registered in the testsuite.
`void` `failure(java.lang.String message)` Force a failure (=assertion) for the current test entity (test/testclass/testfile/testsuite).
`void` `failure(java.lang.String message, ScriptStackTrace stackTrace)` Called from the javascript runner.
`static java.lang.String[]` `getReportTypes()` Get a list of available test report types.
`ITest` `getTest()` Get the current unit test.
`ITestFile` `getTestFile()` Get the currently executed test file instance.
`ITestSuite` `getTestSuite()` Get the current test suite.
`void` `ignore(java.lang.String reason)` Ignore the current test, the current testfile or test suite.
`void` `initialize(IScriptEngine engine, IEnvironment environment)` Provides script engine and environment instances.
`ITestSuiteDefinition` `loadTestSuiteDefinition(java.lang.Object location)` Load a test suite definition from a given resource.
`void` `saveTestSuiteDefinition(ITestSuiteDefinition testsuite, java.lang.Object fileLocation)` Save a test suite definition to a file.
`void` `setTestTimeout(long timeout)` Set the timeout for the current test.
`void` `setThrowOnFailure(boolean throwOnFailure)` Changes behavior for assertion handling.
`void` `startTest(java.lang.String title, java.lang.String description)` Start a specific unit test.

### Methods inherited from class org.eclipse.ease.modules.AbstractScriptModule

`getScriptEngine`

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### UnitTestModule

    public UnitTestModule()

### Method Detail

#### initialize

    public void initialize(IScriptEngine engine,
                           IEnvironment environment)

Description copied from interface: `IScriptModule`
Provides script engine and environment instances.

Specified by:
  `initialize` in interface `IScriptModule`
Overrides:
  `initialize` in class `AbstractScriptModule`
Parameters:
  `engine` - script engine this module is loaded in
  `environment` - environment module that tracks this module

#### startTest

    public final void startTest(java.lang.String title,
                                @ScriptParameter(defaultValue="")
                                java.lang.String description)

Start a specific unit test. Started tests should be terminated by an `endTest()`.

Parameters:
  `title` - name of test
  `description` - short test description

#### endTest

    public final void endTest()

End the current test. Does nothing if no test was started.

#### getTestSuite

    public ITestSuite getTestSuite()

Get the current test suite.

Returns:
  test suite instance

#### getTestFile

    public ITestFile getTestFile()

Get the currently executed test file instance. The test file is not a file instance but the runtime representation of a testsuite test file.

Returns:
  test file instance

#### addMetaData

    public void addMetaData(java.lang.String name,
                            java.lang.Object value)

Append generic data to the current test, testfile or test suite.

Parameters:
  `name` - key to use. Has to be unique for this test object
  `value` - data to be stored

#### assertEquals

    public static IAssertion assertEquals(java.lang.Object expected,
                                          java.lang.Object actual,
                                          @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                          java.lang.Object errorDescription)

Expect two objects to be equal.

Parameters:
  `expected` - expected result
  `actual` - actual result
  `errorDescription` - optional error text to be displayed when not equal
Returns:
  assertion containing comparison result

#### assertMatch

    public static IAssertion assertMatch(java.lang.String pattern,
                                         java.lang.String candidate,
                                         @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                         java.lang.String errorMessage)

Asserts when provided value does not match to a given regular expression pattern.

Parameters:
  `pattern` - pattern to match
  `candidate` - text to be matched
  `errorMessage` - error message in case of a mismatch
Returns:
  assertion depending on `actual` value

#### assertNotEquals

    public static IAssertion assertNotEquals(java.lang.Object expected,
                                             java.lang.Object actual,
                                             @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                             java.lang.Object errorDescription)

Expect two objects not to be equal.

Parameters:
  `expected` - unexpected result
  `actual` - actual result
  `errorDescription` - optional error text to be displayed when equal
Returns:
  assertion containing comparison result

#### assertNull

    public static IAssertion assertNull(java.lang.Object actual,
                                        @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                        java.lang.Object errorDescription)

Asserts when provided value is not `null`.

Parameters:
  `actual` - value to verify
  `errorDescription` - optional error description
Returns:
  assertion depending on `actual` value

#### assertNotNull

    public static IAssertion assertNotNull(java.lang.Object actual,
                                           @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                           java.lang.Object errorDescription)

Asserts when provided value is `null`.

Parameters:
  `actual` - value to verify
  `errorDescription` - optional error description
Returns:
  assertion depending on `actual` value

#### assertTrue

    public static IAssertion assertTrue(java.lang.Boolean actual,
                                        @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                        java.lang.Object errorDescription)

Asserts when provided value is `false`.

Parameters:
  `actual` - value to verify
  `errorDescription` - optional error description
Returns:
  assertion depending on `actual` value

#### assertFalse

    public static IAssertion assertFalse(java.lang.Boolean actual,
                                         @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                         java.lang.Object errorDescription)

Asserts when provided value is `true`.

Parameters:
  `actual` - value to verify
  `errorDescription` - optional error description
Returns:
  assertion depending on `actual` value

#### setThrowOnFailure

    public void setThrowOnFailure(boolean throwOnFailure)

Changes behavior for assertion handling. By default assertions do not cause an exception to be thrown, which supports classic (functional) test mode. Object oriented test mode enhances exceptions to be thrown on assertions.

Parameters:
  `throwOnFailure` - `true` to thow exceptions on assertions

#### assertion

    public final void assertion(IAssertion reason)
                         throws AssertionException

Create a new assertion for the current test. According to the assertion status an error might be added to the current testcase.

Parameters:
  `reason` - assertion to be checked
Throws:
  `AssertionException` - in case `setThrowOnFailure(boolean)` is enabled

#### addTestClass

    public ITestContainer addTestClass(java.lang.String className)

#### ignore

    public void ignore(@ScriptParameter(defaultValue="")
                       java.lang.String reason)

Ignore the current test, the current testfile or test suite. What is ignored depends on the scope this command is executed in.

Parameters:
  `reason` - message why the test got ignored.

#### failure

    public void failure(java.lang.String message)

Force a failure (=assertion) for the current test entity (test/testclass/testfile/testsuite).

Parameters:
  `message` - failure message

#### failure

    public void failure(java.lang.String message,
                        ScriptStackTrace stackTrace)

Called from the javascript runner.

Parameters:
  `message` - failure message
  `stackTrace` - stacktrace of failure event

#### getTest

    public ITest getTest()

Get the current unit test.

Returns:
  the current test or a generic global test scope if called outside of a valid testcase

#### error

    public void error(java.lang.String message)
               throws AssertionException

Force an error for the current test entity (test/testclass/testfile/testsuite).

Parameters:
  `message` - error message
Throws:
  `AssertionException` - containing the provided message

#### error

    public void error(java.lang.String message,
                      ScriptStackTrace stackTrace)

Called from the javascript runner.

Parameters:
  `message` - error message
  `stackTrace` - stacktrace of error event

#### setTestTimeout

    public void setTestTimeout(long timeout)

Set the timeout for the current test. If test execution takes longer than the timeout, the test is marked as failed.

Parameters:
  `timeout` - timeout in [ms]

#### executeUserCode

    public java.lang.Object executeUserCode(java.lang.String location)
                                     throws java.lang.Exception

Execute code registered in the testsuite.

Parameters:
  `location` - name of the code fragment to execute.
Returns:
  execution result
Throws:
  `java.lang.Exception` - when no user specific code can be found or the injected code throws

#### getReportTypes

    public static java.lang.String[] getReportTypes()

Get a list of available test report types.

Returns:
  String array containing available report types

#### createReport

    public void createReport(java.lang.String reportType,
                             ITestEntity suite,
                             java.lang.Object fileLocation,
                             java.lang.String title,
                             java.lang.String description,
                             @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                             java.lang.Object reportData)
                      throws java.io.IOException,
                             CoreException

Create a test report file.

Parameters:
  `reportType` - type of report; see getReportTypes() for values
  `suite` - `ITestEntity` to be reported
  `fileLocation` - location where report should be stored
  `title` - report title
  `description` - report description (ignored by some reports)
  `reportData` - additional report data. Specific to report type
Throws:
  `CoreException` - when we could not write to a workspace file
  `java.io.IOException` - when we could not write to the file system

#### loadTestSuiteDefinition

    public ITestSuiteDefinition loadTestSuiteDefinition(java.lang.Object location)
                                                 throws java.io.IOException

Load a test suite definition from a given resource.

Parameters:
  `location` - location to load from
Returns:
  test suite definition
Throws:
  `java.io.IOException` - when reading of definition fails

#### saveTestSuiteDefinition

    public void saveTestSuiteDefinition(ITestSuiteDefinition testsuite,
                                        java.lang.Object fileLocation)
                                 throws java.io.IOException,
                                        CoreException

Save a test suite definition to a file.

Parameters:
  `testsuite` - definition to save
  `fileLocation` - location to save file to (file system or workspace)
Throws:
  `CoreException` - when we could not write to a workspace file
  `java.io.IOException` - when we could not write to the file system