Test
Default type of any test method. See Testing.
Methods
assertEquals
<function> Asserts that two values are equal. Optionally a message may be provided that is displayed instead of the default message.
Receiver
Test
Type Arguments
T
Arguments
expected - T
actual - T
optional message - Text
Usage
@test
function testEqPassing(test: Test) -> {
test.assertEquals(someValue, theSameValue);
};
@test
function testEqPassingWithMessage(test: Test) -> {
test.assertEquals(someValue, theSameValue, "The number of boxes should equal the number of shipped products.");
};
@test
function testEqFailing(test: Test) -> {
test.assertEquals(someValue, someOtherValue);
};
assertFails
<function> Run an action that is expected to fail. If the action fails as expected, the test passes and the result contains the corresponding failure message. If the action does not fail, the test fails. Optionally a message may be provided that is displayed instead of the default message.
Receiver
Test
Type Arguments
T
Arguments
action - () -> T
optional message - Text
Returns
Text
Usage
protocol[p] Foo(n: Number) {
require(n > threshold, "n must exceed the threshold");
};
@test
function testFailsPassing(test: Test) -> {
// Test passes because the `require` clause fails.
var message = test.assertFails(function() returns Foo -> Foo['p'](belowThreshold));
};
@test
function testFailsPassingWithMessage(test: Test) -> {
// Test passes because the `require` clause fails.
var message = test.assertFails(function() returns Foo -> Foo['p'](belowThreshold), "`require` clause failure expected.");
};
@test
function testFailsFailing(test: Test) -> {
// Test fails because `require` does not fail.
test.assertFails(function() returns Foo -> Foo['p'](aboveThreshold));
};
assertFailsWith
<function> Run an action that is expected to fail with a specific runtime error code. If the action fails as expected, the test passes and the result contains the corresponding failure message. If the action does not fail, the test fails. Optionally a message may be provided that is displayed instead of the default message.
Receiver
Test
Type Arguments
T
Arguments
action - () -> T
runtimeError - Number
optional message - Text
Returns
Text
Usage
See Errors for the runtime error codes that can be used.
@test
function testsFailsWithPasses(test: Test) -> {
// This test passes because the error code thrown by a failing `require` is R14
test.assertFailsWith(function() -> Foo['p'](belowThreshold), 14);
};
// This test fails because the error code thrown by a failing `require` is R14, not R15
test.assertFailsWith(function() -> Foo['p'](belowThreshold), 15)
assertFalse
<function>
Asserts that the provided value is false. Optionally a message may be provided that is displayed instead of the default message.
Receiver
Test
Arguments
actual - Boolean
optional message - Text
Usage
@test
function testFalsePassing(test: Test) -> {
test.assertFalse(conditionFalse);
};
@test
function testFalsePassingWithMessage(test: Test) -> {
test.assertFalse(conditionFalse, "The pump should be off.");
};
@test
function testFalseFailing(test: Test) -> {
test.assertFalse(conditionTrue);
};
assertNotEquals
<function> Asserts that two values are not equal. Optionally a message may be provided that is displayed instead of the default message.
Receiver
Test
Type Arguments
T
Arguments
notExpected - T
actual - T
optional message - Text
Usage
@test
function testNePassing(test: Test) -> {
test.assertNotEquals(someValue, anotherValue);
};
@test
function testNePassingWithMessage(test: Test) -> {
test.assertNotEquals(someValue, anotherValue, "After delivery the target should have been updated.");
};
@test
function testNeFailing(test: Test) -> {
test.assertNotEquals(someValue, sameValue);
};
assertTrue
<function>
Asserts that the provided value is true. Optionally a message may be provided that is displayed instead of the default message.
Receiver
Test
Arguments
actual - Boolean
optional message - Text
Usage
@test
function testTruePassing(test: Test) -> {
test.assertTrue(conditionThatIsTrue);
};
@test
function testTruePassingWithMessage(test: Test) -> {
test.assertTrue(conditionThatIsTrue, "The pump should have been turned on.");
};
@test
function testTrueFailing(test: Test) -> {
test.assertTrue(conditionThatIsFalse);
};
expectNotifications
<function> Asserts whether a specific number of notification was emitted with the given predicate.
Receiver
Test
Type Arguments
Protocol
Notification
Predicate
Arguments
proto - Protocol - Protocol must be a protocol instance from which the notification is expected to have been sent
notif - Notification - Notification must be the notification by-name which is expected to have been sent
count - Number - Number the expected number of notifications matching the predicate
predicate - Predicate - Predicate must be a functional type with Boolean return type taking as arguments the same in-order argument types as its aforementioned notification n: N. Its evaluation should always succeed with either true or false. If the notification has no arguments, the function type should also have no arguments. The arguments are passed with the notification values that were emitted.
Usage
notification NoEarthquake() returns Unit;
notification Earthquake(a: Number, b: Text) returns Unit;
notification Aftershock(scale: Number) returns Unit;
protocol[a] Mountain() {
permission[a] quake() {
notify NoEarthquake();
notify Earthquake(5, "2");
notify Aftershock(3);
};
};
@test
function testMyNotifications(test: Test) -> {
var m = Mountain['a']();
m.quake['a']();
test.expectNotifications(m, NoEarthquake, 1, function() returns Boolean -> true);
test.expectNotifications(m, Earthquake, 1, function(a: Number, b: Text) returns Boolean -> a == 5 && b == "2");
test.expectNotifications(m, Aftershock, 0, function(scale: Number) -> scale > 3);
};
comment
<function> Sets an additional message that will be printed during the test.
Receiver
Test
Arguments
message - Text
Returns
Test
setTime
<function> Sets the internal scheduler and runtime clock during testing.
Receiver
Test
Arguments
dateTime - DateTime
Returns
DateTime
sleep
<function>
Calls Thread.sleep(...) internally for millis milliseconds.
Receiver
Test
Arguments
millis - Number
storeProtocol
<function>
Stores a protocol reference that can be retrieved using loadProtocol. When used within the EngineMigrationTester, the reference will be accessible for its lifetime. Outside of EngineMigrationTester, the reference is only valid within the scope of that test function. StoreProtocol can be called multiple times. When storing a protocol using an existing key, the new reference will replace the previous reference, rendering the previous protocol inaccessible. Any protocol that is not stored will not be persisted. When calling storeProtocol, only state changes made up to the invocation site will be retained. Any changes made afterwards, will be lost. For further reference, see the EngineMigrationTester Javadocs.
Type Arguments
T
Arguments
test - Test - The Test object
key - Text - The text key used to identify the given protocol. Used to recall the protocol.
proto - T - The protocol to be stored. It must be a protocol instance or an error will occur.
Usage
This function must be used in conjunction with the EngineMigrationTester. Otherwise, the protocol reference will only exist within the function scope.
protocol[party] Foo(var n: Number) {}
tester.runTo("1.0.0")
tester.runNPL(
name = "test-1.0.0",
snippet = """
package test;
use npl.Foo;
const party = 'aParty';
@test
function test100(test: Test) -> {
var foo = Foo[party](100);
test.assertEquals(100, foo.n);
storeProtocol(test, "foo", foo);
};
""".trimIndent(),
)
loadProtocol
<function>
Retrieves a stored protocol reference. See storeProtocol. If the given key has not been associated with a protocol, an empty Optional will be returned. If the protocol reference is found, an Optional<T> will be returned, where T is the type specified by the given type argument. If the type argument given does not match the referenced protocol, an error will be returned. For further reference, see the EngineMigrationTester Javadocs.
Type Arguments
T
Arguments
test - Test - : The Test object
key - Text - : The text key used to retreive Protocol
Returns
Optional<T>
Usage
This function must be used when testing with the EngineMigrationTester. Otherwise, an empty Optional will always be returned.
protocol[party] Foo(private var n: Number) {
permission[party] getValue() returns Number { return n; }
}
tester.runTo("1.0.1")
tester.runNPL(
name = "test-1.0.1",
snippet = """
package test;
use npl.Foo;
const party = 'aParty';
@test
function test101(test: Test) -> {
var foo = loadProtocol<Foo>(test, "foo").getOrFail();
test.assertEquals(100, foo.getValue[party]());
};
""".trimIndent(),
)