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,
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.
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.collection | 1.2.0 |
Contains API of the test module.
Aliases | |
TestComparator | Source Codeshared TestComparator=> Comparison(TestDescription, TestDescription) Alias for functions which compare two tests. |
TestFilter | Source Codeshared TestFilter=> Boolean(TestDescription) Alias for functions which filter tests. Should return true if the given test should be run. |
TestSource | Source Codeshared TestSource=> Module|Package|ClassDeclaration|FunctionDeclaration|Class<Anything,Nothing>|FunctionModel<Anything,Nothing>|String Alias for program elements from which tests can be run. |
Annotations | |
afterTest | Source 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 class StarshipTest() { beforeTest void init() => starship.chargePhasers(); afterTest void dispose() => starship.shutdownSystems(); |
beforeTest | Source 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 class StarshipTest() { beforeTest void init() => starship.chargePhasers(); afterTest void dispose() => starship.shutdownSystems(); |
ignore | Source 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:
|
test | Source Codeshared TestAnnotation test() Marks a function as being a test.
Only nullary functions should be annotated with Example of simplest test: test shared void shouldAlwaysSucceed() {} |
testExecutor | Source Codeshared TestExecutorAnnotation testExecutor(ClassDeclaration executor) Annotation to specify custom 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:
|
testListeners | Source Codeshared TestListenersAnnotation testListeners({ClassDeclaration+} listeners) Annotation to specify custom 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:
|
testSuite | Source 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:
|
AfterTestAnnotation | Source Codeshared final AfterTestAnnotation Annotation class for |
BeforeTestAnnotation | Source Codeshared final BeforeTestAnnotation Annotation class for |
IgnoreAnnotation | Source Codeshared final IgnoreAnnotation Annotation class for |
TestAnnotation | Source Codeshared final TestAnnotation Annotation class for |
TestExecutorAnnotation | Source Codeshared final TestExecutorAnnotation Annotation class for |
TestListenersAnnotation | Source Codeshared final TestListenersAnnotation Annotation class for |
TestSuiteAnnotation | Source Codeshared final TestSuiteAnnotation Annotation class for |
Values | |
error | Source Codeshared error error A test state is error, if it propagates any exception which is not an |
failure | Source Codeshared failure failure A test state is failure, if it propagates an |
ignored | Source Codeshared ignored ignored A test state is ignored, if it is marked with |
success | Source Codeshared success success A test state is success, if it complete normally (that is, does not throw an exception). |
Functions | |
assertEquals | Source 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: Throws
|
assertFalse | Source Codeshared void assertFalse(Boolean condition, String? message = null) Fails the test if the condition is true. Parameters:
Throws
|
assertNotEquals | Source 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: Throws
|
assertNotNull | Source Codeshared void assertNotNull(Anything val, String? message = null) Fails the test if the given value is null. Parameters:
Throws
|
assertNull | Source Codeshared void assertNull(Anything val, String? message = null) Fails the test if the given value is not null. Parameters:
Throws
|
assertThatException | Source Codeshared ExceptionAssert assertThatException(Throwable|Anything() exceptionSource) Fails the test if expected exception isn't thrown. Parameters:
Throws
|
assertTrue | Source Codeshared void assertTrue(Boolean condition, String? message = null) Fails the test if the condition is false. Parameters:
Throws
|
createTestRunner | Source Codeshared TestRunner createTestRunner(TestSource[] sources, TestListener[] listeners = [], TestFilter filter = ..., TestComparator comparator = ...) Create a new Parameters:
|
defaultTestComparator | Source Codeshared Comparison defaultTestComparator(TestDescription description1, TestDescription description2) Default test comparator sort tests alphabetically. |
defaultTestFilter | Source Codeshared Boolean defaultTestFilter(TestDescription description) Default test filter, always return true. |
equalsCompare | Source 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 |
fail | Source Codeshared void fail(String? message = null) Throws an Parameters:
Throws
|
Interfaces | |
TestExecutor | Source Codeshared TestExecutor Represent a strategy how to run test.
During test execution notifies test mechanism about significant events via given Custom implementation can be specify via
|
TestListener | Source 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 runner = createTestRunner{ sources = [`module com.acme`]; listeners = [RingingListener()];}; … or better declaratively with usage of testListeners({`class RingingListener`}) module com.acme; |
TestRunContext | Source Codeshared TestRunContext Represents a context in which a test is executed, it's used by |
TestRunResult | Source Codeshared TestRunResult Represents a summary result of the test run. |
TestRunner | Source Codeshared TestRunner Represents a facade for running tests. Instances are usually created via the |
Classes | |
ExceptionAssert | Source Codeshared ExceptionAssert An assertions applicable to exceptions, see |
TestDescription | Source Codeshared TestDescription Describes a test, or a group of tests, can be arranged in a tree. |
TestResult | Source Codeshared TestResult Represents a detailed result of the execution of a particular test. |
TestState | Source Codeshared abstract TestState The result state of test execution. |
error | Source Codeshared error A test state is error, if it propagates any exception which is not an |
failure | Source Codeshared failure A test state is failure, if it propagates an |
ignored | Source Codeshared ignored A test state is ignored, if it is marked with |
success | Source Codeshared success A test state is success, if it complete normally (that is, does not throw an exception). |
Exceptions | |
AssertionComparisonError | Source Codeshared AssertionComparisonError Thrown to indicate that two values which should have been “the same” (according to some comparison function) were in fact different. |