Skip to main content
The Items surface provides tools for creating and inspecting item stacks outside of an inventory context. ItemTestAdapter lets you build stacks and read their properties, while ItemAssert covers durability, metadata, and stackability checks. Item testing ensures that your mod’s items have the correct properties at creation time, that durability degrades and breaks as expected, that stackability rules are enforced, and that custom metadata is preserved. These are the kind of subtle bugs that slip through manual testing - an item that should not stack suddenly stacking, or a tool that starts with zero durability instead of max.

ItemStack Immutability

An important concept to understand: item stacks created with ctx.createStack(...) are standalone snapshot objects. They are not placed in any inventory, and modifying the stack does not affect any inventory slot. If you need to test item behavior inside an inventory, use the Inventory & Loot surface instead. When you read a stack’s properties (ID, size, durability), you are reading the values at the time of creation. If the game engine modifies the underlying item type later, the stack object you hold may not reflect those changes.

Complete Example Suite

Adapter Methods

Assertion Methods

When to Test Items

Item tests are most valuable when:
  • Your mod defines custom items with specific durability values
  • You need to verify stackability rules for new item types
  • Your items carry custom metadata (enchantments, upgrades, custom properties)
  • You want regression tests to catch changes in item type definitions after server updates

Next Steps