Skip to main content

rell.test.block

rell.test.block type provides methods for creating and executing test blocks within the Rell testing framework.

Test block timestamps​

The timestamps of Rell test blocks are deterministic, and determined by the following rules:

  1. If the next block's timestamp was set explicitly via rell.test.set_next_block_time() or rell.test.set_next_block_time_delta(), that timestamp is used for the next block, and is then discarded (and will not be used by subsequent blocks).
  2. If the next block's timestamp was not set explicitly, and there is a previous block, the next block's timestamp is the timestamp of the previous block plus the block interval.
  3. If the next block's timestamp was not set explicitly, and there is no previous block, the timestamp of the next (and first) block will be 2020-01-01 00:00:00 UTC.

Example​

Here's a simple example of building and running a test block:

operation foo(x: integer) { ... }
operation bar(s: text) { ... }

...

val tx1 = rell.test.tx(foo(123), bar('ABC'))
    .sign(rell.test.keypairs.bob)           // signing with the "Bob" test keypair
    ;

val tx2 = rell.test.tx(bar('XYZ'))
    .sign(rell.test.keypairs.bob)
    .sign(rell.test.keypairs.alice)         // tx2 is signed with both "Bob" and "Alice" keypairs
    ;

rell.test.block()
    .tx(tx1)
    .tx(tx2)
    .run()                                  // execute the block consisting of two transactions: tx1 and tx2
    ;

Constructors​

rell.test.block()​

Creates an empty block builder.

Parameters:

  • None

Returns:

  • An empty block builder object.

rell.test.block(tx: rell.test.tx...)​

Creates a block builder with the specified transactions.

Parameters:

  • tx: rell.test.tx... - One or more test transactions to include in the block.

Returns:

  • A block builder object containing the specified transactions.

rell.test.block(txs: list<rell.test.tx>)​

Creates a block builder with the specified list of transactions.

Parameters:

  • txs: list<rell.test.tx> - A list of test transactions to include in the block.

Returns:

  • A block builder object containing the specified list of transactions.

rell.test.block(op: rell.test.op...)​

Creates a block builder with one transaction containing the specified operations.

Parameters:

  • op: rell.test.op - One or more test operations to include in a single transaction within the block.

Returns:

  • A block builder object containing one transaction with the specified operations.

rell.test.block(ops: list<rell.test.op>)​

Creates a block builder with one transaction containing the specified list of operations.

Parameters:

  • ops: list<rell.test.op> - A list of test operations to include in a single transaction within the block.

Returns:

  • A block builder object containing one transaction with the specified list of operations.

Functions​

function tx(tx: rell.test.tx...)​

Adds the specified transactions to the block.

Parameters:

  • tx: rell.test.tx... - One or more test transactions to add to the block.

Returns:

  • The block builder object (allowing for method chaining).

function tx(txs: list<rell.test.tx>)​

Adds the specified list of transactions to the block.

Parameters:

  • txs: list<rell.test.tx> - A list of test transactions to add to the block.

Returns:

  • The block builder object (allowing for method chaining).

function tx(op: rell.test.op...)​

Adds one transaction containing the specified operations to the block.

Parameters:

  • op: rell.test.op... - One or more test operations to include in the transaction.

Returns:

  • The block builder object (allowing for method chaining).

function tx(ops: list<rell.test.op>)​

Adds one transaction containing the specified list of operations to the block.

Parameters:

  • ops: list<rell.test.op> - A list of test operations to add to the block.

Returns:

  • The block builder object (allowing for method chaining).

function copy(): rell.test.block​

Returns a copy of this block builder object.

Parameters:

  • None

Returns:

  • A copy of the block builder object.

function run(): void​

Runs the block.

Parameters:

  • None

Returns:

  • Nothing.

function run_must_fail(expected: text? = null): rell.test.failure​

Runs this block and expects it to fail. If an expected message is passed, it will pass only if the failure message contains the expected message. Throws an exception on success, not on failure.

Parameters:

  • expected (optional): Text indicating the expected error message.

Returns:

  • A rell.test.failure object if the block fails as expected. Throws an exception if the block succeeds unexpectedly.

Example​

operation will_fail_sometimes(will_fail: booelan) {
    require(!will_fail, "This operation has failed");
}

function test_fails() {
    val block = rell.test.block(will_fail_sometimes(true));
    block.run_must_fail();
    block.run_must_fail("has failed");
}