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.
string | RegExp
required
Pattern to match GUI title.
number
Max wait time in ms (default: 5000).
LiveGuiHandle
Examples:
gui.locator(predicate)
Creates a locator for items matching the predicate.
function
required
(item: ItemWrapper) => booleanGuiItemLocator
Examples:
locator.click(options?)
Clicks the located item with automatic retry.
number
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.
string
required
Text that should appear in lore.
number
Max wait time in ms (default: 5000ms).
number
Check interval in ms (default: 100ms).