Source Code

The ceylon.test module is a simple framework to write repeatable tests.

Tests execute the code of the module under test and can make assertions about what it does. For example,

  • do functions, when called with certain arguments, return the expected results?
  • do classes behave as required?
  • etc.

The usual way to use this module is to write your tests (which make calls to the declarations under test) as top level functions or as methods of top level classes, annotating them with test().

For example, here is a trivial test() function, which will always succeed.

test
void shouldAlwaysSucceed() {}

Assertions can be evaluated by using the language's assert statement or with the various assert... functions, for example:

assert(is Hobbit frodo);
assert(exists ring);

assertNotEquals(frodo, sauron);
assertThatException(() => gandalf.castLightnings()).hasType(`NotEnoughMagicPowerException`);

It's also perfectly acceptable to throw AssertionError directly.

A test function which completes without propagating an exception is classified as a success. A test function which propagates an AssertionError is classified as a failure. A test function which propagates any other type of Exception is classified as an error.

Test functions can be grouped together inside a class.

class YodaTest() {

    test
    void shouldBeJedi() {
        assert(yoda is Jedi);
    }

    test
    void shouldHavePower() {
        assert(yoda.midichloriansCount > 1k);
    }

Or several tests can be combined into testSuite() and then run together.

testSuite({`class YodaTest`,
           `class DarthVaderTest`,
           `function starOfDeathTestSuite`})
void starwarsTestSuite() {}   

Common initialization logic can be placed into separate functions, which run before or after each test.

class StarshipTest() {

    beforeTest void init() => starship.chargePhasers();

    afterTest void dispose() => starship.shutdownSystems();

Sometimes you want to temporarily disable a test or a group of tests, this can be done via the ignore() annotation.

test
ignore("still not implemented")
void shouldBeFasterThanLight() {

The most convenient way how to run tests is to use IDE integration or via command line tool ceylon test.

Tests can be also run programmatically, via interface TestRunner and its factory method createTestRunner(), but this API is usually not necessary to use directly.

By: Tom Bentley, Tomáš Hradec
License: Apache Software License
Packages
ceylon.test

Contains API of the test module.

ceylon.test.core

Contains core implementations of the test module.

ceylon.test.event

Contains events of the test module.

Dependencies
ceylon.collection1.2.0

Contains API of the test module.

Aliases
TestComparatorSource Codeshared TestComparator=> Comparison(TestDescription, TestDescription)

Alias for functions which compare two tests.

TestFilterSource Codeshared TestFilter=> Boolean(TestDescription)

Alias for functions which filter tests. Should return true if the given test should be run.

TestSourceSource Codeshared TestSource=> Module|Package|ClassDeclaration|FunctionDeclaration|Class<Anything,Nothing>|FunctionModel<Anything,Nothing>|String

Alias for program elements from which tests can be run.

Annotations
afterTestSource Codeshared AfterTestAnnotation afterTest()

Marks a function which will be run after each test in its scope.

It allow to place common initialization logic into separate place. Only nullary functions should be annotated with afterTest.

class StarshipTest() {

    beforeTest 
    void init() => starship.chargePhasers();

    afterTest 
    void dispose() => starship.shutdownSystems();
beforeTestSource Codeshared BeforeTestAnnotation beforeTest()

Marks a function which will be run before each test in its scope.

It allow to place common initialization logic into separate place. Only nullary functions should be annotated with beforeTest.

class StarshipTest() {

    beforeTest 
    void init() => starship.chargePhasers();

    afterTest 
    void dispose() => starship.shutdownSystems();
ignoreSource Codeshared IgnoreAnnotation ignore(String reason = "")

Marks a test or group of tests which should not be executed.

It can be set on several places: on concrete test, on class which contains tests, on whole package or even module.

test
ignore("still not implemented")
void shouldBeFasterThanLight() {
Parameters:
  • reason = ""

    Reason why the test is ignored.

testSource Codeshared TestAnnotation test()

Marks a function as being a test. Only nullary functions should be annotated with test.

Example of simplest test:

test
shared void shouldAlwaysSucceed() {}
testExecutorSource Codeshared TestExecutorAnnotation testExecutor(ClassDeclaration executor)

Annotation to specify custom TestExecutor implementation, which will be used for running test.

It can be set on several places: on concrete test, on class which contains tests, on whole package or even module. If multiple occurrences will be found, the most closest will be used.

 testExecutor(`class ArquillianTestExecutor`)
 package com.acme;
Parameters:
testListenersSource Codeshared TestListenersAnnotation testListeners({ClassDeclaration+} listeners)

Annotation to specify custom TestListeners, which will be used during running test.

It can be set on several places: on concrete test, on class which contains tests, on whole package or even module. If multiple occurrences will be found, all listeners will be used.

testListeners({`class DependencyInjectionTestListener`,
               `class TransactionalTestListener`})
package com.acme;
Parameters:
testSuiteSource Codeshared TestSuiteAnnotation testSuite({Declaration+} sources)

Annotation to specify test suite, which allow combine several tests or test suites and run them together.

testSuite({`class YodaTest`,
           `class DarthVaderTest`,
           `function starOfDeathTestSuite`})
shared void starwarsTestSuite() {}
Parameters:
  • sources

    The program elements from which tests will be executed.

AfterTestAnnotationSource Codeshared final AfterTestAnnotation

Annotation class for afterTest().

BeforeTestAnnotationSource Codeshared final BeforeTestAnnotation

Annotation class for beforeTest().

IgnoreAnnotationSource Codeshared final IgnoreAnnotation

Annotation class for ignore().

TestAnnotationSource Codeshared final TestAnnotation

Annotation class for test().

TestExecutorAnnotationSource Codeshared final TestExecutorAnnotation

Annotation class for testExecutor().

TestListenersAnnotationSource Codeshared final TestListenersAnnotation

Annotation class for testListeners().

TestSuiteAnnotationSource Codeshared final TestSuiteAnnotation

Annotation class for testSuite()

Values
errorSource Codeshared error error

A test state is error, if it propagates any exception which is not an AssertionError.

failureSource Codeshared failure failure

A test state is failure, if it propagates an AssertionError.

ignoredSource Codeshared ignored ignored

A test state is ignored, if it is marked with ignore() annotation.

successSource Codeshared success success

A test state is success, if it complete normally (that is, does not throw an exception).

Functions
assertEqualsSource Codeshared void assertEquals(Anything actual, Anything expected, String? message = null, Boolean compare(Anything val1, Anything val2) = ...)

Fails the test if the given values are not equal according to the given compare function.

Parameters:
  • actual

    The actual value to be checked.

  • expected

    The expected value.

  • message = null

    The message describing the problem.

  • compare = equalsCompare(actual, expected)

    The compare function.

Throws
assertFalseSource Codeshared void assertFalse(Boolean condition, String? message = null)

Fails the test if the condition is true.

Parameters:
  • condition

    The condition to be checked.

  • message = null

    The message describing the problem.

Throws
assertNotEqualsSource Codeshared void assertNotEquals(Anything actual, Anything unexpected, String? message = null, Boolean compare(Anything val1, Anything val2) = ...)

Fails the test if the given values are equal according to the given compare function.

Parameters:
  • actual

    The actual value to be checked.

  • unexpected

    The expected value.

  • message = null

    The message describing the problem.

  • compare = equalsCompare(actual, unexpected)

    The compare function.

Throws
assertNotNullSource Codeshared void assertNotNull(Anything val, String? message = null)

Fails the test if the given value is null.

Parameters:
  • val

    The value to be checked.

  • message = null

    The message describing the problem.

Throws
assertNullSource Codeshared void assertNull(Anything val, String? message = null)

Fails the test if the given value is not null.

Parameters:
  • val

    The value to be checked.

  • message = null

    The message describing the problem.

Throws
assertThatExceptionSource Codeshared ExceptionAssert assertThatException(Throwable|Anything() exceptionSource)

Fails the test if expected exception isn't thrown.

Parameters:
  • exceptionSource

    The checked exception or callback which should throw exception.

Throws
assertTrueSource Codeshared void assertTrue(Boolean condition, String? message = null)

Fails the test if the condition is false.

Parameters:
  • condition

    The condition to be checked.

  • message = null

    The message describing the problem.

Throws
createTestRunnerSource Codeshared TestRunner createTestRunner(TestSource[] sources, TestListener[] listeners = [], TestFilter filter = ..., TestComparator comparator = ...)

Create a new TestRunner for the given test sources and configures it according to the given parameters.

Parameters:
  • sources

    The program elements from which tests will be executed.

  • listeners = []

    The listeners which will be notified about events during the test run.

  • filter = defaultTestFilter

    A filter function for determining which tests should be run. Returns true if the test should be run. The default filter always returns true.

  • comparator = defaultTestComparator

    A comparator used to sort the tests, used tests in certain order. The default comparator runs the tests in alphabetical order.

defaultTestComparatorSource Codeshared Comparison defaultTestComparator(TestDescription description1, TestDescription description2)

Default test comparator sort tests alphabetically.

defaultTestFilterSource Codeshared Boolean defaultTestFilter(TestDescription description)

Default test filter, always return true.

equalsCompareSource Codeshared Boolean equalsCompare(Anything obj1, Anything obj2)

Compares two things. Returns true if both are null or both are non-null and are the same according to Object.equals().

failSource Codeshared void fail(String? message = null)

Throws an AssertionError to fail a test.

Parameters:
  • message = null

    The message describing the problem.

Throws
Interfaces
TestExecutorSource Codeshared TestExecutor

Represent a strategy how to run test. During test execution notifies test mechanism about significant events via given TestRunContext.

Custom implementation can be specify via testExecutor() annotation. It should accept two parameters:

  • the first parameter is own test function, represented like FunctionDeclaration
  • the second parameter is class containg this test function, if exists, represented like ClassDeclaration?
TestListenerSource Codeshared TestListener

Represents a listener which will be notified about events that occur during a test run.

Example of simple listener, which triggers alarm whenever test fails.

shared class RingingListener() satisfies TestListener {
    shared actual void testError(TestErrorEvent event) => alarm.ring();
}

… such listener can be used directly when creating TestRunner

TestRunner runner = createTestRunner{
    sources = [`module com.acme`];
    listeners = [RingingListener()];};

… or better declaratively with usage of testListeners() annotation

testListeners({`class RingingListener`})
module com.acme;
TestRunContextSource Codeshared TestRunContext

Represents a context in which a test is executed, it's used by TestExecutors.

TestRunResultSource Codeshared TestRunResult

Represents a summary result of the test run.

TestRunnerSource Codeshared TestRunner

Represents a facade for running tests.

Instances are usually created via the createTestRunner() factory method. For running tests is more convenient to use command line tool ceylon test or use integration with IDE, so it is not necessary to use this API directly.

Classes
ExceptionAssertSource Codeshared ExceptionAssert

An assertions applicable to exceptions, see assertThatException().

TestDescriptionSource Codeshared TestDescription

Describes a test, or a group of tests, can be arranged in a tree.

TestResultSource Codeshared TestResult

Represents a detailed result of the execution of a particular test.

TestStateSource Codeshared abstract TestState

The result state of test execution.

errorSource Codeshared error

A test state is error, if it propagates any exception which is not an AssertionError.

failureSource Codeshared failure

A test state is failure, if it propagates an AssertionError.

ignoredSource Codeshared ignored

A test state is ignored, if it is marked with ignore() annotation.

successSource Codeshared success

A test state is success, if it complete normally (that is, does not throw an exception).

Exceptions
AssertionComparisonErrorSource Codeshared AssertionComparisonError

Thrown to indicate that two values which should have been “the same” (according to some comparison function) were in fact different.