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.

When tests run inside a live server, they share state with the production environment. Isolation strategies control how much of that shared state is protected from test mutations. Choosing the right strategy is critical for test reliability and server safety.

​
The Three Strategies

StrategyProtectsCostBest For
NONENothingZero overheadRead-only tests, pure logic, assertions
SNAPSHOTCreated entitiesTrack + cleanup per suiteEntity creation tests
DEDICATED_WORLDFull world stateWorld create + destroy per suiteBlock, spawn, and integration tests

​
Decision Flowchart

1

Does your test modify ECS components?

If no, use NONE. If yes, continue.
2

Does your test modify blocks or spawn entities?

If no, use SNAPSHOT. If yes, use DEDICATED_WORLD.

​
Side-by-Side Comparison

NONE

No protection. Tests see and modify live server state. Suite instantiation is the only boundary. Fast but risky for mutating tests.

SNAPSHOT

Entities created during the suite are tracked and removed after. Only cleans up created entities - modifications to pre-existing entities and blocks are NOT reverted.

DEDICATED_WORLD

A temporary void world is created for the suite. All entities, blocks, and state are destroyed when the suite completes. Full isolation at the cost of world creation overhead.

​
Usage

Set the isolation strategy on @HytaleSuite: 
// Default -- no isolation
@HytaleSuite("Pure Logic Tests")
public class PureLogicTests { }

// Snapshot -- created entity cleanup
@HytaleSuite(value = "Component Tests", isolation = IsolationStrategy.SNAPSHOT)
public class ComponentTests { }

// Dedicated world -- full isolation
@HytaleSuite(value = "World Tests", isolation = IsolationStrategy.DEDICATED_WORLD)
public class WorldTests { }

​
When to Use Each

Use NONE when your tests:
  • Only read data, never write
  • Test pure functions or utility classes
  • Test codec round-trips (no server state involved)
  • Verify annotations, configuration, or metadata
@HytaleSuite("Math Utils Tests")
public class MathUtilsTests {
    @HytaleTest
    void testClamp() {
        HytaleAssert.assertEquals(5, MathUtils.clamp(10, 0, 5));
    }
}
Use SNAPSHOT when your tests:
  • Create entities and need them cleaned up automatically
  • Attach components to newly created entities
  • Need created entities removed after the suite without destroying the world
@HytaleSuite(value = "Stat Modifier Tests", isolation = IsolationStrategy.SNAPSHOT)
public class StatModifierTests {
    @EcsTest
    void testApplyModifier(EcsTestContext ctx) {
        Object ref = ctx.createEntity();
        // Entity will be removed after suite
    }
}
Use DEDICATED_WORLD when your tests:
  • Place or break blocks
  • Spawn and kill entities
  • Need a clean, predictable world state
  • Test multi-step flows (spawn -> modify -> verify -> cleanup)
@HytaleSuite(value = "Block Tests", isolation = IsolationStrategy.DEDICATED_WORLD)
public class BlockTests {
    @WorldTest
    void testBlockPlacement(WorldTestContext ctx) {
        ctx.setBlock(0, 64, 0, "Rock_Sandstone");
        // Clean world -- no interference from existing blocks
    }
}
Using NONE for tests that mutate server state is dangerous. Changes made by your tests will persist after the test run, potentially affecting live gameplay or other test suites.

​
Next Steps