# HRTK - Hytale Runtime Testing Kit

## Docs

- [Profiling with spark](https://docs.hrtk.frotty27.com/advanced/profiling-with-spark.md): Use spark to find server hotspots, then write HRTK benchmarks to track and prevent regressions.
- [Annotations Reference](https://docs.hrtk.frotty27.com/api/annotations.md): Complete table of all 26 HRTK annotations with descriptions and links.
- [Contexts Reference](https://docs.hrtk.frotty27.com/api/contexts.md): Method tables for TestContext, EcsTestContext, WorldTestContext, and BenchmarkContext.
- [Flow Tests Overview](https://docs.hrtk.frotty27.com/flows/overview.md): What flow tests are, why they matter, and how tick-waiting enables multi-step integration testing.
- [Spawn-Kill-Loot Flow](https://docs.hrtk.frotty27.com/flows/spawn-kill-loot.md): Complete flow test example: spawn an entity, verify its tier, kill it, and verify loot drops.
- [Writing Custom Flows](https://docs.hrtk.frotty27.com/flows/writing-custom-flows.md): How to design and structure your own multi-step flow tests for complex gameplay scenarios.
- [Modder Test Catalog](https://docs.hrtk.frotty27.com/guides/test-catalog.md): A copy-paste reference of tested Hytale API methods with complete test examples for every surface.
- [How It Works](https://docs.hrtk.frotty27.com/how-it-works.md): Understand the architecture behind HRTK: two-artifact design, JAR scanning, command-triggered execution, threading, and crash protection.
- [Installation](https://docs.hrtk.frotty27.com/installation.md): How to add HRTK to your mod project and install the server plugin.
- [HRTK - Hytale Runtime Testing Kit](https://docs.hrtk.frotty27.com/introduction.md): The first runtime testing framework for Hytale server mods. Test your mod inside a live server with real ECS, events, commands, combat, and more.
- [Isolation: DEDICATED_WORLD](https://docs.hrtk.frotty27.com/isolation/dedicated-world.md): A temporary void world is created for the suite and destroyed after. Full isolation for block and spawn tests.
- [Isolation: NONE](https://docs.hrtk.frotty27.com/isolation/none.md): No isolation - tests run directly against live server state.
- [Isolation Overview](https://docs.hrtk.frotty27.com/isolation/overview.md): Compare the three isolation strategies: NONE, SNAPSHOT, and DEDICATED_WORLD.
- [Isolation: SNAPSHOT](https://docs.hrtk.frotty27.com/isolation/snapshot.md): Created entities are tracked during the suite and removed after. Best for component mutation tests.
- [Changelog](https://docs.hrtk.frotty27.com/project/changelog.md): Release history for HRTK.
- [Example Mod Test Reference](https://docs.hrtk.frotty27.com/project/example-mod-tests.md): Every test in the HRTK example mod explained - what it tests, expected results, and why it matters.
- [Roadmap](https://docs.hrtk.frotty27.com/project/roadmap.md): Future plans for HRTK: block read/write improvements, entity type spawning, benchmark comparison, and more.
- [Quickstart](https://docs.hrtk.frotty27.com/quickstart.md): Write your first HRTK test in 5 minutes.
- [Commands](https://docs.hrtk.frotty27.com/running/commands.md): Complete reference for all /hrtk commands: run, list, bench, results, scan, watch, and export.
- [Console Output](https://docs.hrtk.frotty27.com/running/console-output.md): Understand the format of HRTK test results in the server console.
- [File Export](https://docs.hrtk.frotty27.com/running/file-export.md): JSON and HTML export formats for test results, generated by /hrtk export.
- [Server Architecture](https://docs.hrtk.frotty27.com/server/architecture.md): The internal pipeline: discovery, runner, context injection, and result collection.
- [AI and Pathfinding](https://docs.hrtk.frotty27.com/surfaces/ai.md): Inspect NPC AI state, test pathfinding availability, and verify AI behavior.
- [Benchmarks](https://docs.hrtk.frotty27.com/surfaces/benchmarks.md): Measure performance with @Benchmark, BenchmarkContext, warmup/iteration configuration, and manual timing.
- [Blocks](https://docs.hrtk.frotty27.com/surfaces/blocks.md): Test block types, materials, states, and placement in the world.
- [Chat](https://docs.hrtk.frotty27.com/surfaces/chat.md): Test chat message content and broadcasting.
- [Chunks](https://docs.hrtk.frotty27.com/surfaces/chunks.md): Test chunk loading state and chunk operations.
- [Codec Testing](https://docs.hrtk.frotty27.com/surfaces/codecs.md): Test serialization round-trips, decode correctness, and malformed input handling with CodecAssert.
- [Command Testing](https://docs.hrtk.frotty27.com/surfaces/commands.md): Test command execution, output verification, and permissions with CommandAssert and MockCommandSender.
- [Crafting](https://docs.hrtk.frotty27.com/surfaces/crafting.md): Test crafting recipe existence and recipe registry queries.
- [Death & Respawn](https://docs.hrtk.frotty27.com/surfaces/death-respawn.md): Test death causes, item loss on death, and the respawn system with DeathComponent assertions.
- [ECS Testing](https://docs.hrtk.frotty27.com/surfaces/ecs.md): Test entity creation, component operations, and ECS queries with EcsAssert, EcsTestContext, and @EcsTest.
- [Effects](https://docs.hrtk.frotty27.com/surfaces/effects.md): Test status effects, invulnerability, and effect counts with EffectAssert.
- [Event Testing](https://docs.hrtk.frotty27.com/surfaces/events.md): Capture, assert, and inspect events with EventAssert and EventCapture during test execution.
- [Game Modes](https://docs.hrtk.frotty27.com/surfaces/game-modes.md): Test GameMode enum values, GameModeType asset resolution, and ChangeGameModeEvent capture.
- [Inventory & Loot](https://docs.hrtk.frotty27.com/surfaces/inventory-and-loot.md): Test inventory slots, item stacks, and loot drop lists with InventoryAssert and LootAssert.
- [Items](https://docs.hrtk.frotty27.com/surfaces/items.md): Create item stacks, inspect durability, metadata, and test stackability.
- [NPCs](https://docs.hrtk.frotty27.com/surfaces/npc.md): Spawn and inspect NPC entities, verify roles, variants, and despawn state.
- [Permissions](https://docs.hrtk.frotty27.com/surfaces/permissions.md): Test permission checks, mock sender permissions, and permission assertions.
- [Persistence](https://docs.hrtk.frotty27.com/surfaces/persistence.md): Test world save paths and player storage availability.
- [Physics](https://docs.hrtk.frotty27.com/surfaces/physics.md): Test entity velocity, forces, speed, and ground detection.
- [Players](https://docs.hrtk.frotty27.com/surfaces/players.md): Test player entities, game modes, mock players, and world assignment.
- [Plugins](https://docs.hrtk.frotty27.com/surfaces/plugins.md): Test plugin loading state and plugin discovery.
- [Projectiles](https://docs.hrtk.frotty27.com/surfaces/projectiles.md): Test projectile module availability.
- [Scheduling](https://docs.hrtk.frotty27.com/surfaces/scheduling.md): Test world thread execution and world alive state.
- [Stats & Combat](https://docs.hrtk.frotty27.com/surfaces/stats-and-combat.md): Assert on health, damage, death, stat modifiers, and knockback with StatsAssert and CombatAssert.
- [UI Testing](https://docs.hrtk.frotty27.com/surfaces/ui.md): Test server-side UI pages, command captures, and element operations with UIAssert and UITestAdapter.
- [Weather](https://docs.hrtk.frotty27.com/surfaces/weather.md): Test weather state and forced weather configuration.
- [World Testing](https://docs.hrtk.frotty27.com/surfaces/world.md): Test world state, block operations, entity spawning, and positioning with WorldAssert and WorldTestContext.
- [Async & Tick Waiting](https://docs.hrtk.frotty27.com/writing-tests/async-and-tick-waiting.md): Handle server tick timing with waitTicks(), awaitCondition(), and @AsyncTest for tests that span multiple ticks.
- [Filtering & Tags](https://docs.hrtk.frotty27.com/writing-tests/filtering-and-tags.md): Use @Tag, @Order, @Disabled, and @DisplayName to organize tests and run targeted subsets.
- [Lifecycle Hooks](https://docs.hrtk.frotty27.com/writing-tests/lifecycle-hooks.md): Use @BeforeAll, @AfterAll, @BeforeEach, and @AfterEach to set up and tear down test state.
- [Parameterized Tests](https://docs.hrtk.frotty27.com/writing-tests/parameterized-tests.md): Run the same test logic with multiple input values using @ParameterizedTest and @ValueSource.
- [Test Suites](https://docs.hrtk.frotty27.com/writing-tests/test-suites.md): Organize tests with @HytaleSuite, configure isolation strategies, and apply suite-level tags.
- [Testing Mod APIs](https://docs.hrtk.frotty27.com/writing-tests/testing-mod-apis.md): How to test your mod's custom APIs, components, and events with HRTK - patterns and pitfalls from real-world testing.
- [Timeouts & Repetition](https://docs.hrtk.frotty27.com/writing-tests/timeouts-and-repetition.md): Control test time limits with @Timeout and run tests multiple times with @RepeatedTest.
- [Your First Test](https://docs.hrtk.frotty27.com/writing-tests/your-first-test.md): Step-by-step guide to writing and running your first HRTK test inside a Hytale server plugin.

## OpenAPI Specs

- [openapi](https://docs.hrtk.frotty27.com/api-reference/openapi.json)