API Reference

Test Runner API

`test(name, options?, fn)`

Defines an individual test case.

string

required

The title/description of the test.

number

Runs N independent instances of the test simultaneously with distinct leased accounts to detect race conditions.

Partial<EnvironmentCapabilities>

Environment capabilities required for this test to execute.

string[]

List of environment names where this test is allowed to run.

import { test, expect } from '@plugwright/runner';

test('race condition check', { concurrency: 3 }, async ({ player }) => {
  player.chat('/claim');
  await expect(player).toHaveReceivedMessage(/Claimed|already claimed/);
});

`describe.serial(name, options?, fn)`

Groups tests that execute sequentially while retaining the same player/bot session and leased account across all tests in the block.

string

required

The title/description of the serial block.

string

Specific account name to lease from the environment’s account pool.

number

Runs N independent copies of the entire ordered serial chain at the same time.

import { describe, test, expect } from '@plugwright/runner';

describe.serial('kit lifecycle', () => {
  test('claim kit', async ({ player }) => {
    player.chat('/kit starter');
  });

  test('is on cooldown', async ({ player }) => {
    player.chat('/kit starter');
    await expect(player).toHaveReceivedMessage('cooldown');
  });
});

`afterAll(fn)`

Registers a hook that runs once per instance of the enclosing describe.serial block, after its last executed test — whether the block finished all its tests, stopped early on a failure, or a test in it was skipped. Only valid inside describe.serial. Not called if the block never got its player (the initial connect failed). A throwing hook is logged, not fatal.

(ctx: TestContext) => Promise<void> | void

required

The cleanup hook.

import { describe, test, afterAll } from '@plugwright/runner';

describe.serial('vip trial', () => {
  test('grants the trial permission', async ({ player, server }) => {
    await server.execute(`lp user ${player.username} permission settemp vip.trial true 15m`);
  });

  afterAll(async ({ player, server }) => {
    // Runs even if a later test in the block fails or gets skipped.
    await server.execute(`lp user ${player.username} permission unsettemp vip.trial`);
  });

  test('sees the vip shop', async ({ player }) => { /* ... */ });
});

`player` / `bot` Object

The player or bot object represents a real Minecraft client connected to the test server.

Methods

`player.chat(message)`

Sends a chat message or command.

string

required

The message or command to send.

player.chat('/spawn');

`player.gui(options)`

Waits for a GUI to open matching the title and returns a live handle.

string | RegExp

required

Pattern to match GUI title.

const gui = await player.gui({ title: 'Shop' });
const button = gui.locator(i => i.displayName.includes('Confirm'));

`player.makeOp()`

Grants operator status to the player.

await player.makeOp();
player.chat('/admin'); // Now has permission

`player.deOp()`

Removes operator status from the player.

await player.deOp();

`player.setGameMode(mode)`

Changes the player’s game mode.

string

required

‘survival’ | ‘creative’ | ‘adventure’ | ‘spectator’

await player.setGameMode('creative');

`player.teleport(x, y, z)`

Teleports the player to coordinates.

await player.teleport(0, 100, 0);

`player.giveItem(item, count?)`

Gives items to the player.

await player.giveItem('diamond', 64);

`player.clearInventory(item?, options?)`

Clears the player’s inventory and waits until the client-side inventory state reflects it. If an item name is specified, only that item is cleared.

await player.clearInventory();
// or clear specific item
await player.clearInventory('diamond');

Properties

Inventory

Access the player’s current inventory state.

string

The randomly generated or assigned name of the bot.

`server` Object

The server object gives you control over the backend Minecraft server.

Methods

`server.execute(command)`

Executes a command from the server console.

string

required

The console command to execute.

await server.execute(`give ${player.username} diamond 64`);

Exported Utilities

The Plugwright framework exports several utility functions to help you write robust tests.

`createPlayer()`

Creates a new, independent player bot that joins the server. Useful for multi-user tests.

const player2 = await createPlayer();
player2.chat('/tpa ' + player.username);

string

Connect as this exact name instead of taking whatever the environment’s account pool has free.

string

Names the bot inside a describe.serial block, so a later test in that block gets the same bot back instead of connecting another one.

string

The password an authentication plugin logs username in with. Only for a named bot: a pool account already carries its own, and passing both is an error.

Ask for a name only when the test needs that specific identity — an account somebody provisioned by hand, or a name that came out of an external API. A second bot that is only there to be a second player should stay unnamed, so a stand can lease it from the pool.

const friend = await createPlayer({
    username: 'FriendBot',
    password: process.env.FRIEND_BOT_PASSWORD,
});

Read the password from the environment. Spec files go to git.

`sleep(ms)`

Pauses execution for a specified number of milliseconds.

number

required

Milliseconds to sleep.

await sleep(1000);

`poll(fn, options?)`

Repeatedly executes a function until it returns a value that is not undefined, and returns that value. Useful when you are waiting for an object or value to exist and need to extract it.

function

required

Function to poll.

number

Max wait time in ms (default: 5000ms).

number

Check interval in ms (default: 100ms).

const diamond = await poll(() => player.bot.inventory.items().find(i => i.name === 'diamond'));

`waitForAssertion(fn, options?)`

Executes an assertion function repeatedly until it passes or times out. Ideal for expect statements.

function

required

Assertion function.

await waitForAssertion(() => {
  expect(gui.title).toContain('Shop');
});

`waitUntil(predicate, options?)`

Repeatedly executes a boolean function until it returns true. Useful when you simply want to pause execution until a condition is met, without extracting any data.

await waitUntil(() => player.gameMode === 'creative');

`waitForStable(fn, options?)`

Waits for a value returned by a function to remain unchanged for a specified duration. Useful for waiting for a UI to finish animating or loading.

function

required

Function to evaluate.

number

Time the value must remain stable in ms (default: 500ms).

await waitForStable(() => player.inventory.items.length);

Get Started

Documentation

Environments

Maintaining

Test Runner API

`test(name, options?, fn)`

`describe.serial(name, options?, fn)`

`afterAll(fn)`

`player` / `bot` Object

Methods

`player.chat(message)`

`player.gui(options)`

`player.makeOp()`

`player.deOp()`

`player.setGameMode(mode)`

`player.teleport(x, y, z)`

`player.giveItem(item, count?)`

`player.clearInventory(item?, options?)`

Properties

`server` Object

Methods

`server.execute(command)`

Exported Utilities

`createPlayer()`

`sleep(ms)`

`poll(fn, options?)`

`waitForAssertion(fn, options?)`

`waitUntil(predicate, options?)`

`waitForStable(fn, options?)`

​Test Runner API

​test(name, options?, fn)

​describe.serial(name, options?, fn)

​afterAll(fn)

​player / bot Object

​Methods

​player.chat(message)

​player.gui(options)

​player.makeOp()

​player.deOp()

​player.setGameMode(mode)

​player.teleport(x, y, z)

​player.giveItem(item, count?)

​player.clearInventory(item?, options?)

​Properties

​server Object

​Methods

​server.execute(command)

​Exported Utilities

​createPlayer()

​sleep(ms)

​poll(fn, options?)

​waitForAssertion(fn, options?)

​waitUntil(predicate, options?)

​waitForStable(fn, options?)

Test Runner API

`test(name, options?, fn)`

`describe.serial(name, options?, fn)`

`afterAll(fn)`

`player` / `bot` Object

Methods

`player.chat(message)`

`player.gui(options)`

`player.makeOp()`

`player.deOp()`

`player.setGameMode(mode)`

`player.teleport(x, y, z)`

`player.giveItem(item, count?)`

`player.clearInventory(item?, options?)`

Properties

`server` Object

Methods

`server.execute(command)`

Exported Utilities

`createPlayer()`

`sleep(ms)`

`poll(fn, options?)`

`waitForAssertion(fn, options?)`

`waitUntil(predicate, options?)`

`waitForStable(fn, options?)`