Acton standard libraryTesting

expect

expect.tolk standard library file

Module for high-level assertion API.

This module provides a fluent "expect" style API for writing test assertions. It wraps the lower-level Assert functions and provides a more readable syntax. It supports a wide range of types including integers, booleans, slices, addresses, tuples, maps, and optionals.

Examples:

// Simple value check
expect(total).toEqual(100);

// Comparison
expect(balance).toBeGreater(ton("1.0"));

// Approximate check (useful for gas calculations)
expect(gasUsed).toBeApproxEqRel(expectedGas, 10); // within 10%

// Map check
expect(balances).toContainKey(userAddress);
expect(balances.get(userAddress)).toEqual(ton("50"));

Definitions

`Expectation`

struct Expectation<T> {
    /// The value to be expected.
    private value: T
    /// The type of the value to be expected.
    private valueType: string
    /// The location of the expectation to be printed in the error message.
    /// This field is set by the test framework and should not be set manually.
    private location: string
}

Internal struct to represent an expectation for a value.

Don't use this struct directly. Use the expect function instead.

Example:

expect(10).toEqual(10);

`Expectation<T>.create`

fun Expectation<T>.create(value: T, valueType: string, location: string): Expectation<T>

Internal function to create a new expectation for the given value.

Don't use this function directly. Use the expect function instead.

Example:

expect(10).toEqual(10);

`Expectation<T>.fail`

fun Expectation<T>.fail(self, message: string): never

Fails this expectation at its location. A convenient wrapper to be used in Expectation<T>.xxx methods instead of Assert.fail.

Example:

fun Expectation<int>.toBeTen(self) {
    if (self.value != 10) {
        self.fail("integer is not 10");
    }
}

`Expectation<T>.toEqual`

fun Expectation<T>.toEqual<U>(self, expected: U): void

Asserts that actual value is equal to expected value.

Example:

expect(10).toEqual(10);

`Expectation<T>.toEqualDecimal`

fun Expectation<T>.toEqualDecimal(self, expected: T, decimals: int): void

Asserts that actual value is equal to expected value as decimal with given precision.

Comparison itself is exact (no rounding is applied to actual or expected values). decimals controls only failure-message formatting: decimal point insertion, trailing-zero trimming, and normalized integer-style output (.0).

Example:

expect(ton("1.5")).toEqualDecimal(ton("1.5"), 9);

`Expectation<T>.toNotEqual`

fun Expectation<T>.toNotEqual<U>(self, expected: U): void

Asserts that actual value is not equal to expected value.

Example:

expect(10).toNotEqual(20);

`Expectation<T>.toBeLess`

fun Expectation<T>.toBeLess<U>(self, expected: U): void

Asserts that actual value is less than expected value.

Example:

expect(5).toBeLess(10);

`Expectation<T>.toBeGreater`

fun Expectation<T>.toBeGreater<U>(self, expected: U): void

Asserts that actual value is greater than expected value.

Example:

expect(10).toBeGreater(5);

`Expectation<T>.toBeLessOrEqual`

fun Expectation<T>.toBeLessOrEqual<U>(self, expected: U): void

Asserts that actual value is less than or equal to expected value.

Example:

expect(5).toBeLessOrEqual(10);
expect(10).toBeLessOrEqual(10);

`Expectation<T>.toBeGreaterOrEqual`

fun Expectation<T>.toBeGreaterOrEqual<U>(self, expected: U): void

Asserts that actual value is greater than or equal to expected value.

Example:

expect(10).toBeGreaterOrEqual(5);
expect(10).toBeGreaterOrEqual(10);

`Expectation<int>.toBeApproxEqAbs`

fun Expectation<int>.toBeApproxEqAbs(self, expected: int, maxDelta: int): void

Asserts that actual value is approximately equal to expected value using absolute difference.

Example:

expect(10).toBeApproxEqAbs(15, 10); // ok, difference is 5, which is less than maximum allowed difference of 10
expect(10).toBeApproxEqAbs(20, 5); // error, difference is 10, which is greater than maximum allowed difference of 5

`Expectation<int>.toBeApproxEqRel`

fun Expectation<int>.toBeApproxEqRel(self, expected: int, maxDelta: int): void

Asserts that actual value is approximately equal to expected value using relative percentage difference.

Relative delta is computed as: floor(abs(actual - expected) * 100 / abs(actual)). The assertion passes when this computed percentage is less than or equal to maxDelta.

Zero branch: if actual == 0, only expected == 0 passes; any non-zero expected is treated as infinite delta and fails.

Example:

expect(1000).toBeApproxEqRel(1099, 9);
expect(0).toBeApproxEqRel(0, 0);

`Expectation<T?>.toBeNull`

fun Expectation<T?>.toBeNull(self): void

Asserts that actual value is null.

Example:

expect(null).toBeNull();

`Expectation<T?>.toBeNotNull`

fun Expectation<T?>.toBeNotNull(self): void

Asserts that actual value is not null.

Example:

val someValue: int? = cond ? 10 : null;
expect(someValue).toBeNotNull();

`Expectation<slice>.toBeNonEmpty`

fun Expectation<slice>.toBeNonEmpty(self): void

Asserts that actual value is not empty (contains some bits of refs).

Example:

expect(someSlice).toBeNonEmpty();

`Expectation<slice>.toBeEmpty`

fun Expectation<slice>.toBeEmpty(self): void

Asserts that actual value is empty (contains 0 bits and 0 refs).

Example:

expect(someSlice).toBeEmpty();

`Expectation<int>.toBeNaN`

fun Expectation<int>.toBeNaN(self): void

Asserts that actual value is NaN.

Example:

expect(nan()).toBeNaN();

`Expectation<int>.toBeNonNaN`

fun Expectation<int>.toBeNonNaN(self): void

Asserts that actual value is not NaN.

Example:

expect(0).toBeNonNaN();

`Expectation<bool>.toBeTrue`

fun Expectation<bool>.toBeTrue(self): void

Asserts that actual value is true.

Example:

expect(true).toBeTrue();

`Expectation<bool>.toBeFalse`

fun Expectation<bool>.toBeFalse(self): void

Asserts that actual value is false.

Example:

expect(false).toBeFalse();

`Expectation<any_address>.toBeInternalAddress`

fun Expectation<any_address>.toBeInternalAddress(self): void

Asserts that actual address is internal.

Example:

expect(addr).toBeInternalAddress();

`Expectation<any_address>.toBeNoneAddress`

fun Expectation<any_address>.toBeNoneAddress(self): void

Asserts that actual address is none.

Example:

expect(addr).toBeNoneAddress();

`Expectation<any_address>.toBeExternalAddress`

fun Expectation<any_address>.toBeExternalAddress(self): void

Asserts that actual address is external.

Example:

expect(addr).toBeExternalAddress();

`Expectation<array<E>>.toContain`

fun Expectation<array<E>>.toContain<U>(self, expected: U): void

Asserts that an array contains the expected value.

Example:

val arr = [1, 2, 3];
expect(arr).toContain(2);

`Expectation<array<E>>.toNotContain`

fun Expectation<array<E>>.toNotContain<U>(self, expected: U): void

Asserts that an array does not contain the expected value.

Example:

val arr = [1, 2, 3];
expect(arr).toNotContain(4);

`Expectation<array<E>>.toBeEmpty`

fun Expectation<array<E>>.toBeEmpty(self): void

Asserts that an array is empty.

Example:

val arr = array<int> [];
expect(arr).toBeEmpty();

`Expectation<BigArray<E>>.toBeEmpty`

fun Expectation<BigArray<E>>.toBeEmpty(self): void

Asserts that an array is empty.

Example:

val txs = net.send(deployer.address, msg);
expect(txs).toBeEmpty();

`Expectation<array<E>>.toBeNonEmpty`

fun Expectation<array<E>>.toBeNonEmpty(self): void

Asserts that an array is not empty.

Example:

val arr = [1, 2, 3];
expect(arr).toBeNonEmpty();

`Expectation<BigArray<E>>.toBeNonEmpty`

fun Expectation<BigArray<E>>.toBeNonEmpty(self): void

Asserts that an array is not empty.

Example:

val txs = net.send(deployer.address, msg);
expect(txs).toBeNonEmpty();

`Expectation<array<E>>.toHaveLength`

fun Expectation<array<E>>.toHaveLength(self, length: int): void

Asserts that an array has the expected length.

Example:

val arr = [1, 2, 3];
expect(arr).toHaveLength(3);

`Expectation<BigArray<E>>.toHaveLength`

fun Expectation<BigArray<E>>.toHaveLength(self, length: int): void

Asserts that an array has the expected length.

Example:

val txs = net.send(deployer.address, msg);
expect(txs).toHaveLength(3);

`Expectation<map<K, V>>.toContainKey`

fun Expectation<map<K, V>>.toContainKey(self, key: K): void

Asserts that a map contains the expected key.

Example:

var map = map<int32, int32> [];
map.set(1, 2);
map.set(2, 3);
expect(map).toContainKey(2);

`Expectation<map<K, V>>.toNotContainKey`

fun Expectation<map<K, V>>.toNotContainKey(self, key: K): void

Asserts that actual value represeneted as map does NOT contain the expected key.

Example:

var map = map<int32, int32> [];
map.set(1, 2);
map.set(2, 3);
expect(map).toNotContainKey(4);

`Expectation<map<K, V>>.toContainValue`

fun Expectation<map<K, V>>.toContainValue(self, value: V): void

Asserts that actual value represeneted as map contains the expected value.

Example:

var map = map<int32, int32> [];
map.set(1, 2);
map.set(2, 3);
expect(map).toContainValue(2);

`Expectation<map<K, V>>.toNotContainValue`

fun Expectation<map<K, V>>.toNotContainValue(self, value: V): void

Asserts that actual value represeneted as map does NOT contain the expected value.

Example:

var map = map<int32, int32> [];
map.set(1, 2);
map.set(2, 3);
expect(map).toNotContainValue(4);

`Expectation<map<K, V>>.toBeEmpty`

fun Expectation<map<K, V>>.toBeEmpty(self): void

Asserts that actual value represeneted as map is empty.

Example:

var map = map<int32, int32> [];
expect(map).toBeEmpty();

`Expectation<map<K, V>>.toBeNonEmpty`

fun Expectation<map<K, V>>.toBeNonEmpty(self): void

Asserts that actual value represeneted as map is not empty.

Example:

var map = map<int32, int32> [];
map.set(1, 2);
map.set(2, 3);
expect(map).toBeNonEmpty();

`Expectation<map<K, V>>.toHaveLength`

fun Expectation<map<K, V>>.toHaveLength(self, length: int): void

Asserts that actual value represeneted as map has the expected length.

Example:

var map = map<int32, int32> [];
map.set(1, 2);
map.set(2, 3);
expect(map).toHaveLength(2);

`expect`

fun expect<T>(value: T, loc: string = reflect.sourceLocationAsString()): Expectation<T>

Creates a new expectation for the given value.

After creation, the expectation can be used to assert the value.

For example:

expect(10).toEqual(10);

Optional location can be provided to specify the location of the expectation to be printed in the error message. You likely don't want to set this manually, as the location will be automatically set by the test framework.

`expectToEndWithExitCode`

fun expectToEndWithExitCode(code: int): void

Sets the expected exit code for the test.

Example:

expectToEndWithExitCode(10);
throw 10; // Test will end with exit code 10 and be considered as passed

Alternatively, you can use @test.fail_with(10) annotation to set the expected exit code for the whole test.

@test.fail_with(10)
get fun `test fail with`() {
    throw 10; // ok
}

This function is more flexible and can be used conditionally in the test.

Last updated on

assert

assert.tolk standard library file

fuzz

fuzz.tolk standard library file

On this page

Definitions ExpectationExpectation<T>.createExpectation<T>.failExpectation<T>.toEqualExpectation<T>.toEqualDecimalExpectation<T>.toNotEqualExpectation<T>.toBeLessExpectation<T>.toBeGreaterExpectation<T>.toBeLessOrEqualExpectation<T>.toBeGreaterOrEqualExpectation<int>.toBeApproxEqAbsExpectation<int>.toBeApproxEqRelExpectation<T?>.toBeNullExpectation<T?>.toBeNotNullExpectation<slice>.toBeNonEmptyExpectation<slice>.toBeEmptyExpectation<int>.toBeNaNExpectation<int>.toBeNonNaNExpectation<bool>.toBeTrueExpectation<bool>.toBeFalseExpectation<any_address>.toBeInternalAddressExpectation<any_address>.toBeNoneAddressExpectation<any_address>.toBeExternalAddressExpectation<array<E>>.toContainExpectation<array<E>>.toNotContainExpectation<array<E>>.toBeEmptyExpectation<BigArray<E>>.toBeEmptyExpectation<array<E>>.toBeNonEmptyExpectation<BigArray<E>>.toBeNonEmptyExpectation<array<E>>.toHaveLengthExpectation<BigArray<E>>.toHaveLengthExpectation<map<K, V>>.toContainKeyExpectation<map<K, V>>.toNotContainKeyExpectation<map<K, V>>.toContainValueExpectation<map<K, V>>.toNotContainValueExpectation<map<K, V>>.toBeEmptyExpectation<map<K, V>>.toBeNonEmptyExpectation<map<K, V>>.toHaveLengthexpectexpectToEndWithExitCode