Description

Annotation on a test method.
Causes an 'error' type of exception to be thrown from the test method.
Will appear in the CLI as an a FAIL_UNSPECIFIED error, unless the @Test annotation on the same test method has an attribute expected-error-id, with 'FAIL_UNSPECIFIED' as its value.
Practically indistinguishable from @Error.

Attributes

Attribute

Name

Required?

Possible

Values

Info

description

No

A string

Provide description of the error. The description written here will not appear in the method's log report.

Location in the test class file

Before a test method.

Examples

The @Failure annotation does not generate a failure ID.

To fail gracefully using the @Failure annotation, the @Test annotation should use expected-error-id, not expected-failure-id as it would for natural failures or failures induced by the fail() operation.

This test will pass.

@Failure with a description. Error caught by @Test.

@Test(expected-error-id: 'FAIL_UNSPECIFIED')

@Failure(description: 'How did this FAILURE happen?')

executeFailure()

{

log(

message: 'Annotated with failure',

log-file-name: 'test_me.log',

log-classifier: 'anyClassifier'

);

}

The result when you run this test:

@Failure properly caught

userme > te #executeFailure
Processing [1] tests
class experiment.test_me   -------------------------------------------------------
1/1        .executeFailure
  Passed                                                                      P[1]
Tests run: 1, Successes: 1, Time elapsed: 0.178 sec

Here is the @Failure annotation again, without a description. It is functionally the same as the above example.

This test will pass.

@Failure without description. Error caught by @Test.

@Test(expected-error-id: 'FAIL_UNSPECIFIED')

@Failure

executeFailure()

{

log(

message: 'Annotated with failure',

log-file-name: 'test_me.log',

log-classifier: 'anyClassifier'

);

}

The following test will not pass. It will end with an error.

@Failure triggers error not caught by @Test

@Test

@Failure

executeFailure()

{

log(

message: 'Annotated with failure',

log-file-name: 'test_me.log',

log-classifier: 'anyClassifier'

);

}

userme > te #executeFailure
Processing [1] tests
class experiment.test_me   -------------------------------------------------------
1/1        .executeFailure
      FAIL_UNSPECIFIED
  Caused an error                                                             E[1]
Tests run: 1, Errors: 1, Time elapsed: 0.16 sec