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 AssertionException directly.

A test function which completes without propogating an exception is classified as a success. A test function which propogates an AssertionException is classified as a failure. A test function which propogates 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);
    }

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() {

Tests can be run programmatically for a whole module, a package or only individual classes and functions. This is usually achieved using the createTestRunner factory method, most simply by giving it the declaration of the module to be run:

value result = createTestRunner([`module com.acme`]).run();
print(result.isSuccess);

Or by enumerating the things to be tested:

value result = createTestRunner([
        `shouldBeFasterThanLight`,
        `StarshipTest`]).run();
print(result.isSuccess);

Although you can implement the TestRunner interface directly, createTestRunner has numerous defaulted parameters which usually mean you don't have to.

Using listeners you can react to important events during test execution, or you can exclude particular tests, or execute them in a specific order.

object ringingListener satisfies TestListener {
    shared actual void testError(TestResult result) => alarm.ring();
}

Boolean integrationTestFilter(TestDescription d) {
    return d.name.endsWith("IntegrationTest");
}

Comparison failFastComparator(TestDescription d1, TestDescription d2) {
    return dateOfLastFailure(d1) <=> dateOfLastFailure(d2);
}

TestRunner runner = createTestRunner{
    sources = [`module com.acme`];
    listeners = [ringingListener];
    filter = integrationTestFilter;
    comparator = failFastComparator;
};
By: Tom Bentley, Tomáš Hradec
License: Apache Software License
Packages
ceylon.test

Contains core public API of the test module.

Contains core public API of the test module.

Aliases
TestComparatorSource Code
shared TestComparator=> Comparison(TestDescription, TestDescription)

Alias for functions which compare two tests.

TestFilterSource Code
shared TestFilter=> Boolean(TestDescription)

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

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

Alias for program elements from which tests can be run.

Annotations
afterTestSource Code
shared AfterTest afterTest()

Marks a function which will be run after each test in its scope. Only nullary functions should be annotated with afterTest.

beforeTestSource Code
shared BeforeTest beforeTest()

Marks an element which should be run before each test in its scope. Only nullary functions should be annotated with beforeTest.

ignoreSource Code
shared Ignore ignore(String reason = "")

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

Parameters:
  • reason = ""

    Reason why the test is ignored.

testSource Code
shared Test test()

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

AfterTestSource Code
shared AfterTest

Annotation class for afterTest.

BeforeTestSource Code
shared BeforeTest

Annotation class for beforeTest.

IgnoreSource Code
shared Ignore

Annotation class for ignore.

TestSource Code
shared Test

Annotation class for test.

Values
errorSource Code
shared error error

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

failureSource Code
shared failure failure

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

ignoredSource Code
shared ignored ignored

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

successSource Code
shared success success

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

Functions
assertEqualsSource Code
shared void assertEquals(Object? actual, Object? expected, String? message = null, Boolean compare(Object? val1, Object? 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 Code
shared 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:
  • AssertionException

    When condition is true.

assertNotEqualsSource Code
shared void assertNotEquals(Object? actual, Object? expected, String? message = null, Boolean compare(Object? val1, Object? val2) = ...)

Fails the test if the given values are 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:
assertNotNullSource Code
shared void assertNotNull(Object? 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:
  • AssertionException

    When val is null.

assertNullSource Code
shared void assertNull(Object? 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:
  • AssertionException

    When val is not null.

assertThatExceptionSource Code
shared ExceptionAssert assertThatException(Exception|Anything() exceptionSource)

Fails the test if expected exception isn't thrown.

Parameters:
  • exceptionSource

    The checked exception or callback which should throw exception.

Throws:
  • AssertionException

    When exceptionSource() doesn't throw an Exception

assertTrueSource Code
shared 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:
  • AssertionException

    When condition is false.

createTestRunnerSource Code
shared 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 the order they are given in the sources parameter.

defaultTestComparatorSource Code
shared Comparison defaultTestComparator(TestDescription description1, TestDescription description2)

Default test comparator, doesn't change tests order.

defaultTestFilterSource Code
shared Boolean defaultTestFilter(TestDescription description)

Default test filter, always return true.

equalsCompareSource Code
shared Boolean equalsCompare(Object? obj1, Object? obj2)

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

failSource Code
shared void fail(String? message = null)

Throws an AssertionException to fail a test.

Parameters:
  • message = null

    The message describing the problem.

Throws:
  • AssertionException

    always

suiteSource Code
shared void suite(String suiteName, <String->Anything()>[] tests)

Deprecated: Deprecated API, use function createTestRunner.

Interfaces
TestDescriptionSource Code

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

TestListenerSource Code

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

TestResultSource Code
shared TestResult

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

TestRunResultSource Code

Represents a summary result of the test run.

TestRunnerSource Code
shared TestRunner

Represents a facade for running tests. Instances are usually created via the createTestRunner factory method.

Classes
ExceptionAssertSource Code

An assertions applicable to exceptions, see assertThatException.

SimpleLoggingListenerSource Code

A TestListener which prints information about test execution to the standard output.

TestStateSource Code
shared abstract TestState

The result state of test execution.

errorSource Code
shared error

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

failureSource Code
shared failure

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

ignoredSource Code
shared ignored

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

successSource Code
shared success

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

Exceptions
AssertionComparisonExceptionSource Code

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