Isolation: SNAPSHOT

IsolationStrategy.SNAPSHOT tracks entities created during your suite and removes them when the suite finishes. This is not a full state snapshot - it only records which entities were created so they can be cleaned up. Existing entities are not captured or restored.

When to Use

Tests that create entities and need them cleaned up automatically
Tests that attach components to newly created entities
Any test where you want created entities removed after the suite

How It Works

Before Suite

HRTK creates a TestEntityTracker that begins recording entity creations in the ECS store.

Test Execution

Your tests run normally, creating entities and mutating ECS state as needed. The tracker records every entity created during the suite.

After Suite

HRTK calls tracker.cleanup() to remove all entities that were created during the suite. Modifications to pre-existing entities are NOT reverted.

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 will be removed 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());
        // Entity will be removed after suite
    }
}

What Is Tracked and What Is Not

Tracked (cleaned up)	Not Tracked (persists)
Entities created during the suite	Modifications to pre-existing entities
Components attached to tracked entities	Block state (placed/broken blocks)
	Stat changes on pre-existing entities
	World-level configuration
	File system changes
	Event listener registrations

SNAPSHOT only removes entities created during the suite. It does NOT revert modifications to pre-existing entities, and it does NOT roll back block changes. If your test modifies existing entities or calls ctx.setBlock(), those changes will persist. Use DEDICATED_WORLD for tests that need full isolation.

Performance

Entity tracking has minimal overhead - it simply records references to created entities during the suite and removes them at the end. The cleanup cost scales with the number of entities created, not the total size of the ECS store. This cost is paid once per suite (not per test).

If your suite creates entities that need cleanup but does not need full world 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");
        // Entity will be removed 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

Isolation: NONE - no protection, fastest
Isolation: DEDICATED_WORLD - full world isolation
Isolation Overview - strategy comparison

Getting Started

Writing Tests

Testing Surfaces

Test Isolation

Flow Testing

Running Tests

API Reference

Server Plugin

Advanced

Guides

Project

When to Use

How It Works

Usage

What Is Tracked and What Is Not

Performance

Complete Example

Next Steps

​When to Use

​How It Works

​Usage

​What Is Tracked and What Is Not

​Performance

​Complete Example

​Next Steps

When to Use

How It Works

Usage

What Is Tracked and What Is Not

Performance

Complete Example

Next Steps