# Test Rell code · Chromia Docs (concept)

> To write unit tests for Rell code, use test module. You need to use the @test annotation to define a test module.

Source: https://docs.chromia.com/rell/tests/

# Test Rell code

On this page

* [Disabling tests](#disabling-tests)
* [Test module (file data\_test.rell ):](#test-module-file-data_testrell)
* [Example of a test module](#example-of-a-test-module)
* [Testing framework overview](#testing-framework-overview)
* [Test builders](#test-builders)
* [Assertions](#assertions)
* [Test keys](#test-keys)
* [Block timestamps](#block-timestamps)
* [Other utilities](#other-utilities)

To write unit tests for [Rell](https://docs.chromia.com/rell/rell-intro/) code, use test module. You need to use the `@test` annotation to define
a test module.

Rell

```
@test module;

function test_foo() {
    assert_equals(2 + 2, 4);
}

function test_bar() {
    assert_equals(2 + 2, 5);
}
```

All functions in a test module that start with `test_` (and a function called exactly `test`) are test functions that're
executed when you run the test module.

If the module has the "\_test" suffix, it becomes a test module for the module that bears the same name without the
suffix. For example, if the module name is `program`, the test module is `program_test`.

💡 **Best practice****▶️ Follow clear and concise test naming conventions**

Test names should clearly state **what** is being tested, not **how**. This improves readability and makes test reports
easier to understand.

* ✅ Prefix test names with `test_`.
* ✅ Focus on business scenarios.
* 🚫 Avoid redundant words like `it_should_` or `_successful`.

  Rell

  ```
  // 🚫 Unclear and verbose
  test_it_should_get_user
  test_return_paginated_users_list_by_id_successful

  // ✅ Clear and focused
  test_get_full_user_profile_by_id
  test_add_ipfs_link_as_user_profile_avatar
  ```

## Disabling tests

The `@disabled` annotation (since 0.15.1) skips tests. Applied to a test module, it skips every test function in that
module and its submodules. Applied to a test function, it skips that function; this works both for functions marked with
`@test` and for test functions named `test` or starting with `test_`.

Rell

```
// Disable all tests in this test module
@test @disabled module;

function test_addition() {
    // not executed
}
```

Rell

```
// Disable a single test function in an otherwise active test module
@test module;

@disabled @test function test_edge_case() {
    // not executed
}

@test function test_happy_path() {
    // executed normally
}
```

Using `@disabled` on a non-test module or a non-test function is a compile error.

To run a test module, use the test command (`chr test`):

Terminal

```
chr test --settings chromia.yml --modules my_test_module
```

For more information, see the [chr test](https://docs.chromia.com/build/cli/commands/test/) topic. Each test function gets executed independently
of others, and a summary gets printed at the end:

Rell

```
TEST RESULTS:

my_test_module:test_foo OK
my_test_module:test_bar FAILED

SUMMARY: 1 FAILED / 1 PASSED / 2 TOTAL

***** FAILED *****
```

### Test module (file `data_test.rell`):

Rell

```
@test module;
import data;

function test_add_user() {
    assert_equals(data.user @* {}(.name), list<text>());

    val tx = rell.test.tx(data.add_user('Bob'));
    assert_equals(data.user @* {}(.name), list<text>());

    tx.run();
    assert_equals(data.user @* {}(.name), ['Bob']);
}
```

💡 **Best practice****▶️ Naming and coverage conventions for Rell tests**

* ✅ **Use descriptive variable names** that clearly reflect user roles or test scenarios.

  Rell

  ```
  // 🚫 Unclear naming
  val (admin_user, _) = owned_tests_utils.create_test_user(admin);
  val (alice_user, _) = owned_tests_utils.create_test_user(alice);

  // ✅ Clear and meaningful naming
  val (admin, _) = owned_tests_utils.create_test_user(admin);
  val (alice, _) = owned_tests_utils.create_test_user(alice);
  ```
* ✅ **Ensure comprehensive test coverage** for entity variations.

  When testing queries like:

  Rell

  ```
  q @* { q.user == user, q.project == project }
  ```

  Make sure to:

  + Test multiple user and project combinations.
  + Vary configurations to cover edge cases.
  + Simulate realistic, business-driven scenarios.

### Example of a test module

Here's an example of a test module:

Rell

```
@test module;
import main;

function test_init(){

    assert_equals((main.user @* {}(.username)).size(),0);
    assert_equals((main.balance @* {}(.user)).size(),0);
    rell.test.tx().op(main.init(rell.test.pubkeys.alice)).run();
    assert_equals(main.user @* {}(.username).size(),1);
    assert_equals(main.balance@{.user == main.user @ { .pubkey == rell.test.pubkeys.alice}}(.amount),1000000);

}

function test_register_user(){

    rell.test.tx().op(main.init(rell.test.pubkeys.alice)).run();
    assert_equals(main.user @* {}(.username).size(),1);
    rell.test.tx().op(main.register_user(rell.test.pubkeys.alice,rell.test.pubkeys.bob,"bob",100)).sign(rell.test.keypairs.alice).run();
    assert_equals(main.user @* {}(.username).size(),2);
    assert_equals(main.user @ {.pubkey == rell.test.pubkeys.bob}(.username),"bob");
    assert_equals(main.balance@{.user == main.user @ {.pubkey == rell.test.pubkeys.bob}}(.amount),100);
}

function test_blocks(){

    val tx1 = rell.test.tx().op(main.init(rell.test.pubkeys.alice));
    val tx2 = rell.test.tx().op(main.register_user(rell.test.pubkeys.alice,rell.test.pubkeys.bob,"bob",100)).sign(rell.test.keypairs.alice);
    val tx3 = rell.test.tx().op(main.create_channel(rell.test.pubkeys.alice,"channel 1")).sign(rell.test.keypairs.alice);
    rell.test.block().tx(tx1).tx(tx2).tx(tx3).run();
    val tx4 = rell.test.tx().op(main.add_channel_member(rell.test.pubkeys.alice,"channel 1","bob")).sign(rell.test.keypairs.alice);
    rell.test.block().tx(tx4).run();
}
```

Unit tests also display the duration of each test case and the overall test suite duration.

Rell

```
    TEST RESULTS:

    OK tests.foobar:test_foo (0.005s)

    FAILED tests.foobar:test_fail_require (0.001s)
    FAILED tests.foobar:test_fail_assert_equals (0.001s)

    SUMMARY: 2 FAILED / 1 PASSED / 3 TOTAL (0.007s)
```

💡 **Best practice**

✅ Focus each **negative test case** on **one specific failure scenario** for clarity.

✅ Use consistent, descriptive naming conventions for failure tests, e.g **function test\_internal\_transfer\_fails**.

✅ Use provided **helper functions** to register users efficiently:

Rell

```
val admin = register_admin();
val alice = register_alice();
val bob = register_bob();
```

🚫 **Avoid verbose setup patterns**:

Rell

```
val admin_account = create_ft3_test_acc(admin_keypair());
```

✅ When using `run_must_fail()`, **always include an expected error message** to make failure reasons explicit:

Rell

```
// Without error message – failure reason unclear
owned.credits_external.create_credit_role("Role")
    .sign(admin.keypair)
    .run_must_fail();

// With error message – failure reason clear
owned.credits_external.create_credit_role("Role")
    .sign(admin.keypair)
    .run_must_fail("Failed to create credit role that already exists");
```

## Testing framework overview

The Rell testing framework provides tools for creating and executing test blocks, transactions, and operations. For
complete API documentation, see the
[rell.test](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/) namespace reference.

### Test builders

Test code uses builder types to construct blocks, transactions, and operations:

* [`rell.test.block`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/block/) – Builder for
  test blocks containing transactions
* [`rell.test.tx`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/tx/) – Builder for test
  transactions containing operations
* [`rell.test.op`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/op/) – Represents a test
  operation call (created by calling any operation)

Builders follow a fluent pattern and support method chaining. All three support `.run()` to execute immediately and
`.run_must_fail()` to assert failure.

### Assertions

The `rell.test` namespace provides assertion functions for verifying test expectations:

* [`assert_equals`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_equals/) – Assert two
  values are equal
* [`assert_not_equals`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_not_equals/) –
  Assert two values are not equal
* [`assert_true`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_true/),
  [`assert_false`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_false/) – Assert
  boolean values
* [`assert_null`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_null/),
  [`assert_not_null`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_not_null/) – Assert
  nullability
* [`assert_gt`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_gt/),
  [`assert_ge`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_ge/),
  [`assert_lt`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_lt/),
  [`assert_le`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_le/) – Assert comparisons
  (greater/less than, or equal)
* [`assert_ge_le`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_ge_le/),
  [`assert_ge_lt`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_ge_lt/),
  [`assert_gt_le`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_gt_le/),
  [`assert_gt_lt`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_gt_lt/) – Assert range
  bounds
* [`assert_fails`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_fails/) – Assert a
  function throws an exception (optionally with a specific message)
* [`assert_events`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/assert_events/) – Assert that
  specific events were emitted in order

### Test keys

Predefined test keypairs are available for signing test transactions. These should **never** be used in production:

* [`rell.test.keypairs`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test.keypairs/) – Full
  keypairs (public and private keys)
* [`rell.test.pubkeys`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test.pubkeys/) – Public
  keys only
* [`rell.test.privkeys`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test.privkeys/) –
  Private keys only

Available names: `alice`, `bob`, `charlie`, `dave`, `eve`, `frank`, `grace`, `heidi`, `trudy`.

### Block timestamps

Test block timestamps are deterministic and controlled through:

* [`rell.test.last_block_time`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/last_block_time/)
  – Timestamp of the last block
* [`rell.test.next_block_time`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/next_block_time/)
  – Timestamp of the next block to be built
* [`rell.test.block_interval`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/block_interval/) –
  Time interval between blocks (default: 10 seconds)
* [`rell.test.set_next_block_time`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/set_next_block_time/)
  – Set next block timestamp explicitly
* [`rell.test.set_next_block_time_delta`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/set_next_block_time_delta/)
  – Set next block timestamp relative to previous block
* [`rell.test.set_block_interval`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/set_block_interval/)
  – Change the default block interval

### Other utilities

* [`rell.test.nop`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/nop/) – Create a no-op
  operation (useful for making transactions unique)
* [`rell.test.get_events`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.test/get_events/) –
  Retrieve all events emitted during the last block construction

tip

For information on writing integration tests using Rell and TypeScript, visit the
[Chromia learning platform](https://chromia.com/learn/rell-integration-test/introduction/).

[View this page on docs.chromia.com](https://docs.chromia.com/rell/tests/)Content mirrored from the live docs
