Skip to main content

How to run tests

Testing is crucial for ensuring your Rell dapp works correctly before deployment. This guide shows you how to write and run tests using the official Rell testing framework.

Prerequisites​

Basic testing workflow​

Step 1: Verify your test files exist​

Test files are automatically discovered in the src/test/ directory. Any .rell file in this directory will be treated as a test module:

# Check test directory structure
ls -la src/test/

# Should show:
# arithmetic_test.rell
# data_test.rell

The test runner automatically discovers and executes all .rell files in the src/test/ directory. Functions starting with test_ within these files are treated as test cases.

Step 2: Run all tests​

chr test

Expected output:

TEST RESULTS:

arithmetic_test:test_addition OK (0.002s)
arithmetic_test:test_subtraction OK (0.001s)
data_test:test_hello_world OK (0.003s)

SUMMARY: 0 FAILED / 3 PASSED / 3 TOTAL (0.006s)

Understanding Rell tests​

Test module basics​

Tests use the @test annotation to define a test module:

@test module;

function test_hello_world() {
    val result = hello_world();
    assert_equals(result, "Hello World!");
}

Functions starting with test_ are automatically executed as tests.

Assertion functions​

Use the official assertion functions provided by Rell:

@test module;

function test_basic_assertions() {
    // Test equality
    assert_equals(2 + 2, 4);

    // Test boolean conditions
    assert_true(5 > 3);
    assert_false(2 > 5);

    // Test comparisons
    assert_lt(3, 5);  // 3 less than 5
    assert_gt(5, 3);  // 5 greater than 3

    // Test that a function fails as expected
    assert_fails(some_failing_function);
}

Running specific tests​

# Run tests from specific module
chr test --modules arithmetic_test

# Run tests from multiple modules
chr test --modules arithmetic_test data_test

# See detailed test output
chr test --verbose

SQL logging for debugging​

Enable SQL query logging to understand how your Rell code translates to database operations:

# Log all SQL queries (both user and system)
chr test --sql-log

# Log only user queries (your dapp's queries)
chr test --sql-log=user

# Log only system queries (internal Chromia queries)
chr test --sql-log=system

# Combine with other options
chr test --sql-log --modules arithmetic_test --verbose

For more information on analyzing SQL statements, see Rell dapp code optimization.

Generating test data with seeder​

The seeder command helps you generate mock data for a local database. This is an early-stage feature and may be subject to change.

Initialize seeder configuration​

# Generate default seeder configuration for all blockchains
chr seeder init

# Generate configuration for specific blockchain
chr seeder init --blockchain my_blockchain

This creates a .chromia/seeder directory with YAML configuration files for each entity in your dapp.

Generate the seeder module​

# Generate seeder modules for all blockchains
chr seeder generate

# Generate for specific blockchain
chr seeder generate --blockchain my_blockchain

This creates src/seeder/seed_[blockchain-name].rell files containing the data generation logic.

For detailed information on using the seeder, see Seeder command documentation and Using the seeder.

Test file organization​

Default test structure:

src/
├── main.rell
└── test/
    ├── arithmetic_test.rell    # Mathematical operation tests
    └── data_test.rell         # Data structure tests

The test runner automatically discovers and executes all .rell files in the src/test/ directory. Functions starting with test_ within these files are treated as test cases.

Debugging test failures​

Reading test output​

When tests fail, the output shows details:

TEST RESULTS:

my_test_module:test_foo OK (0.005s)
my_test_module:test_bar FAILED (0.001s)

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

***** FAILED *****

Adding debug output​

@test module;

function test_with_debug() {
    print("Debug: Starting test");

    val result = my_function();
    print("Debug: Result is " + result);

    assert_equals(result, expected_value);
}

Next steps​

After mastering basic testing:

  1. Deploy your tested dapp with confidence
  2. Learn more about advanced testing patterns in the Rell testing documentation
  3. Explore the Chromia learning platform for integration testing
  4. Run operations to test state modifications
  5. Run queries to verify your test data and operations