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

MethodParametersReturnsDescription
createStackString itemId, int countObjectCreate an item stack with the given ID and count
getItemIdObject stackStringGet the item type ID of the stack
getStackSizeObject stackintGet the current stack count
getDurabilityObject stackintGet current durability value
getMaxDurabilityObject stackintGet maximum durability value
isBrokenObject stackbooleanCheck if the item has zero durability
isStackableObject stackbooleanCheck if the item type supports stacking
getMetadataObject stack, String keyObjectRead a metadata entry from the stack
setMetadataObject stack, String key, Object valuevoidWrite a metadata entry to the stack

Assertion Methods

MethodParametersFailure Message
assertItemIdObject stack, String expected”Expected item ID [expected] but was [actual]“
assertStackSizeObject stack, int expected”Expected stack size [expected] but was [actual]“
assertDurabilityObject stack, int expected”Expected durability [expected] but was [actual]“
assertMaxDurabilityObject stack, int expected”Expected max durability [expected] but was [actual]“
assertBrokenObject stack”Expected item to be broken”
assertNotBrokenObject stack”Expected item to not be broken”
assertStackableObject stack”Expected item to be stackable”
assertNotStackableObject stack”Expected item to not be stackable”
assertHasMetadataObject stack, String key”Expected item to have metadata key [key]“

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