Crucible

An in-game automated testing framework for Hytale server mods. Built by Ionforge Mods.

Crucible runs test suites inside a live Hytale server against the real game engine, not mocks. Write tests that place blocks, spawn entities, manipulate containers, and assert results, all within an
ephemeral test world that cleans up after itself.

Features

- Annotation-based test discovery with lifecycle hooks
- Async tick-based testing
- Tag filtering and parallel execution
- Headless CI mode with JUnit XML and HTML reports
- Event capture and assertion
- Works with or without a connected client

Quick Start

  @Tag("blocks")
  public class MyTests extends AnnotatedTestSuite {
      @Override public String id()   { return "mymod:tests"; }
      @Override public String name() { return "My Tests"; }

      @CrucibleTest
      public TestResult placeAndVerify(TestContext ctx) {
          ctx.placeBlock(0, 0, 0, "Rock_Basalt");
          return ctx.assertBlockIs("basalt placed", 0, 0, 0, "Rock_Basalt");
      }
  }

Requirements

- Hytale Server 2026.05.07+
- Java 25+

Links

- Source & Docs