# How to run tests · Chromia Docs (concept)

> Testing is crucial for ensuring your Rell dapp works correctly before deployment.

Source: https://docs.chromia.com/build/cookbook/cli/run-tests/

# How to run tests

On this page

* [Prerequisites](#prerequisites)
* [Basic testing workflow](#basic-testing-workflow)
* [Step 1: Verify your test files exist](#step-1-verify-your-test-files-exist)
* [Step 2: Run all tests](#step-2-run-all-tests)
* [Understanding Rell tests](#understanding-rell-tests)
* [Test module basics](#test-module-basics)
* [Assertion functions](#assertion-functions)
* [Running specific tests](#running-specific-tests)
* [SQL logging for debugging](#sql-logging-for-debugging)
* [Generating test data with seeder](#generating-test-data-with-seeder)
* [Initialize seeder configuration](#initialize-seeder-configuration)
* [Generate the seeder module](#generate-the-seeder-module)
* [Test file organization](#test-file-organization)
* [Debugging test failures](#debugging-test-failures)
* [Reading test output](#reading-test-output)
* [Adding debug output](#adding-debug-output)
* [Next steps](#next-steps)

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

* [Chromia CLI installed](https://docs.chromia.com/get-started/installation/)
* [Rell dapp project created](https://docs.chromia.com/build/cookbook/cli/create-rell-dapp/)

## 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:

Terminal

```
# 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

Terminal

```
chr test
```

Expected output:

Plain text

```
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:

Rell

```
@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:

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

Terminal

```
# 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:

Terminal

```
# 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](https://docs.chromia.com/rell/analyze-rell-dapp-code/).

## 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

Terminal

```
# 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

Terminal

```
# 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](https://docs.chromia.com/build/cli/commands/seeder/) and
[Using the seeder](https://docs.chromia.com/build/cli/Seeder/seeder-example/).

## Test file organization

Default test structure:

Plain text

```
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:

Plain text

```
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

Rell

```
@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](https://docs.chromia.com/build/cli/commands/deployment/) with confidence
2. Learn more about advanced testing patterns in the [Rell testing documentation](https://docs.chromia.com/rell/tests/)
3. Explore the [Chromia learning platform](https://chromia.com/learn/rell-integration-test/introduction/) for
   integration testing
4. [Run operations](https://docs.chromia.com/build/cookbook/cli/run-operations/) to test state modifications
5. [Run queries](https://docs.chromia.com/build/cookbook/cli/run-queries/) to verify your test data and operations

[View this page on docs.chromia.com](https://docs.chromia.com/build/cookbook/cli/run-tests/)Content mirrored from the live docs
