Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hrtk.frotty27.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through creating a test class, writing test methods, using assertions, and running everything from the server console.
This guide covers HRTK’s built-in testing features. If you’re testing a mod that has its own API (spawn systems, query methods, custom events), see Testing Mod APIs for patterns specific to mod integration testing.

​
Prerequisites

Before you start, make sure:
  • Your mod project uses Gradle (or Maven) and can compile against hrtk-api
  • The hrtk-server plugin JAR is in your server’s plugins/ directory
  • Your server is running with at least one world loaded
hrtk-api is a compile-only dependency. It provides annotations and assertion classes but is not needed at runtime - the server plugin handles everything.

​
Step 1: Add the Dependency

In your mod’s build.gradle, add hrtk-api as a compile-only dependency:
build.gradle
dependencies {
    compileOnly project(':hrtk-api')
    // ... your other dependencies
}

​
Step 2: Create a Test Class

Create a new class in your mod’s source tree. Annotate it with @HytaleSuite to give it a name and group your tests.
MyFirstTests.java
package com.example.mymod.tests;

import com.frotty27.hrtk.api.annotation.HytaleSuite;
import com.frotty27.hrtk.api.annotation.HytaleTest;
import com.frotty27.hrtk.api.assert_.HytaleAssert;

@HytaleSuite("My First Tests")
public class MyFirstTests {

    @HytaleTest
    void mathStillWorks() {
        HytaleAssert.assertEquals(4, 2 + 2);
    }

    @HytaleTest("Addition with message")
    void additionWithCustomName() {
        HytaleAssert.assertEquals("Two plus two should equal four", 4, 2 + 2);
    }
}
The @HytaleTest annotation accepts an optional display name string. If omitted, the method name is used as the display name in test output.

​
Step 3: Use Assertions

HytaleAssert provides a full set of assertion methods. Here are the most common ones: 
HytaleAssert.assertEquals(expected, actual);
HytaleAssert.assertNotEquals(unexpected, actual);
HytaleAssert.assertEquals(3.14, 3.14159, 0.01); // with delta

​
Step 4: Receive Context (Optional)

If your test needs access to the server environment, declare a TestContext parameter. HRTK injects it automatically. 
import com.frotty27.hrtk.api.context.TestContext;

@HytaleTest
void testWithContext(TestContext ctx) {
    ctx.log("Running inside plugin: %s", ctx.getPluginName());
    HytaleAssert.assertNotNull(ctx.getPluginName());
}
Context injection works for TestContext, EcsTestContext, WorldTestContext, BenchmarkContext, and MockCommandSender. The runner inspects your method’s parameter types and provides the right implementation.

​
Step 5: Build and Run

1

Build your mod

Run ./gradlew build to compile your mod JAR with the test classes baked in.
2

Deploy

Copy your mod’s JAR into the server’s plugins/ directory alongside hrtk-server.jar.
3

Start the server

HRTK scans all plugins on startup. You should see a log line like:
HRTK: Found 2 test(s) in 1 suite(s) from plugin 'MyMod'
4

Run tests

From the server console (or in-game with hrtk.admin permission):
/hrtk run

​
Expected Output

After running, you should see formatted results in the console: 
=== HRTK: MyMod ===
  My First Tests
    [PASS] mathStillWorks (2ms)
    [PASS] Addition with message (1ms)

Results: 2 passed, 0 failed, 0 skipped (3ms total)

​
Next Steps

Test Suites

Learn how to organize tests with @HytaleSuite, naming, and isolation strategies.

Lifecycle Hooks

Set up shared state with @BeforeAll, @AfterAll, @BeforeEach, and @AfterEach.

Filtering & Tags

Tag your tests and run subsets with —tag filters.

Assertion Reference

See the full annotation reference for all 24 HRTK annotations.