Skip to main content
IsolationStrategy.SNAPSHOT captures the ECS store state before your suite runs and restores it after. This means any entities you create, components you modify, or stats you change during your tests will be reverted when the suite finishes.

​
When to Use

  • Tests that create entities and attach components
  • Tests that modify stat values, health, or modifiers
  • Tests that add or remove effects
  • Any ECS mutation test where you want automatic rollback

​
How It Works

1

Before Suite

HRTK captures a TestStoreSnapshot of the ECS store from the first available world.
2

Test Execution

Your tests run normally, mutating ECS state as needed. All changes are made against the live store.
3

After Suite

HRTK calls snapshot.restore() to revert the ECS store to its pre-suite state. All entity creations, component changes, and stat modifications are undone.

​
Usage

import com.frotty27.hrtk.api.lifecycle.IsolationStrategy;

@HytaleSuite(value = "ECS Mutation Tests", isolation = IsolationStrategy.SNAPSHOT)
@Tag("ecs")
public class EcsMutationTests {

    @EcsTest
    @Order(1)
    void testCreateAndModify(EcsTestContext ctx) {
        Object ref = ctx.createEntity();
        ctx.putComponent(ref, TransformComponent.getComponentType(),
                         new TransformComponent());
        ctx.flush();

        EcsAssert.assertHasComponent(ctx.getStore(), ref,
                                      TransformComponent.getComponentType());
        // This entity and component will be rolled back after the suite
    }

    @EcsTest
    @Order(2)
    void testRemoveComponent(EcsTestContext ctx) {
        Object ref = ctx.createEntity();
        ctx.putComponent(ref, TransformComponent.getComponentType(),
                         new TransformComponent());
        ctx.flush();

        ctx.removeComponent(ref, TransformComponent.getComponentType());
        ctx.flush();

        EcsAssert.assertNotHasComponent(ctx.getStore(), ref,
                                         TransformComponent.getComponentType());
        // All changes reverted after suite
    }
}

​
What Is Snapshot and What Is Not

CapturedNot Captured
Entity references and their componentsBlock state (placed/broken blocks persist)
Stat values and modifiersWorld-level configuration
Effect controller stateFile system changes
Component attachmentsEvent listener registrations
SNAPSHOT does NOT roll back block changes. If your test calls ctx.setBlock(), those blocks will persist after the snapshot restore. Use DEDICATED_WORLD for tests that modify blocks.

​
Performance

Taking and restoring a snapshot has moderate overhead depending on the size of the ECS store. For servers with thousands of entities, snapshot operations may take tens of milliseconds. This cost is paid once per suite (not per test).
If your suite has many tests that all need ECS isolation, SNAPSHOT is more efficient than DEDICATED_WORLD because it avoids the cost of creating and destroying an entire world.

​
Complete Example

@HytaleSuite(value = "Stat Modifier Tests", isolation = IsolationStrategy.SNAPSHOT)
@Tag("stats")
public class StatModifierTests {

    @EcsTest
    void applyModifierAndVerify(EcsTestContext ctx) {
        Object ref = ctx.createEntity();
        // ... set up entity with stats ...
        ctx.flush();

        // Apply a modifier
        applyModifier(ctx, ref, "test_buff", 10.0f);
        ctx.waitTicks(1);

        StatsAssert.assertHasModifier(ctx.getStore(), ref, getStatType(), "test_buff");
        // Modifier will be rolled back after suite
    }

    @EcsTest
    void removeModifierAndVerify(EcsTestContext ctx) {
        Object ref = ctx.createEntity();
        // ... set up entity with stats and modifier ...
        ctx.flush();

        removeModifier(ctx, ref, "test_buff");
        ctx.waitTicks(1);

        StatsAssert.assertNoModifier(ctx.getStore(), ref, getStatType(), "test_buff");
    }
}

​
Next Steps