org.eclipse.ease.modules.unittest.modules

## Class UnitTestModule

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

All Implemented Interfaces:
  IScriptFunctionModifier, IScriptModule

    public class UnitTestModule
    extends AbstractScriptModule
    implements IScriptFunctionModifier

Library providing UnitTest functionality. Unit tests are parts of a JavaScript file which are embedded between a startTest() and an endTest() function call. Every function result returned inbetween will be checked for a response of type `IAssertion`. If such a response is detected its result will automatically be applied to the current unit test.

### Field Summary

Fields
`static String` `FAIL_ON_ERROR_VARIABLE`
`static String` `INJECTED_MAIN`
`static String` `MODULE_NAME`

### Fields inherited from interface org.eclipse.ease.modules.IScriptFunctionModifier

`RESULT_NAME`

### Constructor Summary

Constructors
Constructor and Description
`UnitTestModule()`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`void` `addMetaData(String key, String data)` Add metadata to the current test object.
`static IAssertion` `assertEquals(Object expected, Object actual, Object errorDescription)` Expect two objects to be equal.
`static IAssertion` `assertFalse(boolean actual, Object errorDescription)` Asserts when provided value is `true`.
`void` `assertion(IAssertion reason)` Create a new assertion for the current test.
`static IAssertion` `assertNotEquals(Object expected, Object actual, Object errorDescription)` Expect two objects not to be equal.
`static IAssertion` `assertNotNull(Object actual, Object errorDescription)` Asserts when provided value is `null`.
`static IAssertion` `assertNull(Object actual, Object errorDescription)` Asserts when provided value is not `null`.
`static IAssertion` `assertTrue(boolean actual, Object errorDescription)` Asserts when provided value is `false`.
`boolean` `createReport(String reportType, TestSuite suite, String fileLocation, String title, String description)` Create a test report file.
`void` `disableAssertions()` Disables automatic assertions in tests.
`void` `enableAssertions()` Enables automatic assertions in tests.
`void` `endTest()` End the current test.
`void` `error(String message)` Add a new error to the current testcase.
`void` `executeUserCode(String identifier)` Insert additional test code at a given code location.
`void` `failure(String message)` Report a new failure for the current UnitTest.
`String` `getPostExecutionCode(Method method)`
`String` `getPreExecutionCode(Method method)`
`static String[]` `getReportTypes()` Get a list of available report types.
`Test` `getTest(String name)` Get a `Test` instance.
`TestFile` `getTestFile()` Get the current `TestFile` instance.
`TestSuite` `getTestSuite()` Get the current `TestSuite` instance.
`void` `ignoreAssertions(int count)` Define amount of upcoming assertions to be ignored.
`TestSuite` `openTestSuite(String filename)` Open a testsuite without executing it.
`TestSuite` `runUnitTest(Object executable)` Run a unit test.
`void` `startTest(String title, String description)` Start a specific unit test.
`static boolean` `waitForCompletion(TestComposite testObject)` Wait until a test entity is completed.

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

`getScriptEngine, initialize`

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

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

### Field Detail

#### MODULE_NAME

    public static final String MODULE_NAME

See Also:
  Constant Field Values

#### INJECTED_MAIN

    public static final String INJECTED_MAIN

See Also:
  Constant Field Values

#### FAIL_ON_ERROR_VARIABLE

    public static final String FAIL_ON_ERROR_VARIABLE

See Also:
  Constant Field Values

### Constructor Detail

#### UnitTestModule

    public UnitTestModule()

### Method Detail

#### runUnitTest

    public TestSuite runUnitTest(Object executable)

Run a unit test. If the file addressed is a suite, then the whole suite is started. If the file is a simple JavaScript file, then a dynamic suite is created that contains just the one file.

Parameters:
  `filename` - location of testsuite or testfile. Must be a file from the workspace
Returns:
  `TestSuite` definition or `null`

#### openTestSuite

    public TestSuite openTestSuite(String filename)
                            throws IOException,
                                   CoreException

Open a testsuite without executing it.

Parameters:
  `filename` - location of testsuite file. Must be a file from the workspace
Returns:
  `TestSuite` definition or `null`
Throws:
  `IOException`
  `CoreException`

#### createReport

    public boolean createReport(String reportType,
                                TestSuite suite,
                                String fileLocation,
                                String title,
                                String description)
                         throws Exception

Create a test report file.

Parameters:
  `reportType` - type of report; see getReportTypes() for values
  `suite` - `TestSuite` to be reported
  `fileLocation` - location where report should be stored
  `title` - report title
  `description` - report description (ignored by some reports)
Returns:
  `true` when report was created successfully
Throws:
  `Exception` - thrown on file write errors

#### getReportTypes

    public static String[] getReportTypes()

Get a list of available report types.

Returns:
  String array containing available report types

#### getPreExecutionCode

    public String getPreExecutionCode(Method method)

Specified by:
  `getPreExecutionCode` in interface `IScriptFunctionModifier`

#### getPostExecutionCode

    public String getPostExecutionCode(Method method)

Specified by:
  `getPostExecutionCode` in interface `IScriptFunctionModifier`

#### startTest

    public final void startTest(String title,
                                @ScriptParameter(defaultValue="")
                                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.

#### assertion

    public final void assertion(IAssertion reason)

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

#### error

    public final void error(String message)

Add a new error to the current testcase.

Parameters:
  `message` - error message

#### failure

    public final void failure(String message)

Report a new failure for the current UnitTest.

Parameters:
  `message` - failure message

#### getTestFile

    public TestFile getTestFile()

Get the current `TestFile` instance.

Returns:
  test file instance

#### getTest

    public Test getTest(@ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                        String name)

Get a `Test` instance. if no name is provided, the current test instance is returned. When provided, this method searches for a test with the given title.

Parameters:
  `name` - test name to look for
Returns:
  current test or `null`

#### getTestSuite

    public TestSuite getTestSuite()

Get the current `TestSuite` instance.

Returns:
  test suite instance

#### executeUserCode

    public final void executeUserCode(String identifier)

Insert additional test code at a given code location. Some code locations are predefined like start test file or start test case. Others may be freely defined by the unit test execution target. Those other tests need to be invoked by the unit tests by calling `executeUserCode(identifier);`.

Parameters:
  `identifier` - code identifier

#### assertEquals

    public static IAssertion assertEquals(Object expected,
                                          Object actual,
                                          @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                          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

#### assertNotEquals

    public static IAssertion assertNotEquals(Object expected,
                                             Object actual,
                                             @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                             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(Object actual,
                                        @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                        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(Object actual,
                                           @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                           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(boolean actual,
                                        @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                        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(boolean actual,
                                         @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                         Object errorDescription)

Asserts when provided value is `true`.

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

#### disableAssertions

    public void disableAssertions()

Disables automatic assertions in tests. When set user generated errors, warnings, failures will still be reported, but assert functions will not report errors. Assertions are automatically enabled on a `startTest(String, String)` command.

#### enableAssertions

    public void enableAssertions()

Enables automatic assertions in tests. This is the default setting for any testfile.

#### ignoreAssertions

    public void ignoreAssertions(int count)

Define amount of upcoming assertions to be ignored. Allows to ignore `count` upcoming assertions (not depending on actual assertion status). Assertions are enabled again once the counter reaches 0,when `enableAssertions()` is called or a new test is started using `startTest(String, String)`.

Parameters:
  `count` - assertions to be ignored

#### waitForCompletion

    public static boolean waitForCompletion(TestComposite testObject)

Wait until a test entity is completed. If the entity is not scheduled this method might stall forever!

Parameters:
  `testObject` - `TestSuite` or `Test` to wait for
Returns:
  `true` on success, `false` if test was interrupted

#### addMetaData

    public void addMetaData(String key,
                            String data)

Add metadata to the current test object. Metadata is stored as a Map, so setting with an already existing keyword will override the previous setting.

Parameters:
  `key` - metadata keyword
  `data` - metadata