Quick Start
Core Concepts
Live Handles vs Snapshots
Live Handle (LiveGuiHandle) - Always reflects the player’s current GUI state:
- Returned by
player.gui({ title }) - Automatically updates when GUI changes
- Use for dynamic, reactive testing
GuiWrapper) - Captures GUI state at a specific moment:
- Legacy API, now deprecated
- Use live handles for new code
Locators
Locators are queries that re-evaluate each time they’re used:Modern API
player.gui({ title, timeout? })
Gets a live handle to a GUI matching the title pattern.
Pattern to match GUI title.
Max wait time in ms (default: 5000).
LiveGuiHandle
Examples:
gui.locator(predicate)
Creates a locator for items matching the predicate.
(item: ItemWrapper) => booleanGuiItemLocator
Examples:
locator.click(options?)
Clicks the located item with automatic retry.
Max wait time in ms (default: 5000ms).
locator.displayName()
Gets the display name of the located item (re-queries each call).
locator.loreText()
Gets the lore text of the located item (re-queries each call).
expect(locator).toHaveLore(text, options?)
Asserts that a locator’s item contains specific lore text, with automatic retry.
Text that should appear in lore.
Max wait time in ms (default: 5000ms).
Check interval in ms (default: 100ms).
gui.title
Gets the current GUI title (or undefined if closed).
Complete Examples
Permission Test
Item Interaction
Dynamic Lore Testing
Paginated GUIs
Player Helper Methods
player.makeOp()
Grants operator status to the player.
player.deOp()
Removes operator status from the player.
player.setGameMode(mode)
Changes the player’s game mode.
‘survival’ | ‘creative’ | ‘adventure’ | ‘spectator’