Skip to main content

rell.test.block

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

When a block is executed, its timestamp is determined by the following rules:

  1. If the block timestamp was explicitly set to a specific value using the rell.test.set_next_block_time() function, that specified value is utilized for the current block, and it is then discarded. Subsequent blocks will not use this specified value.
  2. If no specific timestamp is set, and there is a previous block, the new timestamp is calculated by adding the block interval to the timestamp of the last block.
  3. If no specific timestamp is set, and there is no previous block, the timestamp defaults to 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.block(foo(123), bar('ABC'))
    .sign(rell.test.keypairs.bob)           // signing with the "Bob" test keypair
    ;

val tx2 = rell.test.block(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");
}