MrPippi/docs/paper/testing

Testing Skill — Paper

Purpose

Reference this skill when writing unit tests for Paper plugin code. Covers MockBukkit 4.x for JUnit 5: server mock lifecycle, player mocks, scheduler tick simulation, and testing event handlers and commands without a real server.

When to Use This Skill

• Testing logic in event handlers, commands, or service classes
• Verifying ItemMeta, inventory contents, or PDC values in unit tests
• Running the Bukkit scheduler in tests to confirm delayed/repeating tasks fire correctly
• Testing that custom events are called and cancellable

API Quick Reference

| Class / Method | Purpose | Notes | |---------------|---------|-------| | MockBukkit.mock() | Start the mock server | Returns ServerMock; call in @BeforeEach | | MockBukkit.unmock() | Shut down and clean up | Call in @AfterEach; mandatory | | MockBukkit.load(MyPlugin.class) | Load plugin under test | Returns plugin instance | | ServerMock | Simulated Server | Returned by MockBukkit.mock() | | server.addPlayer() | Add a simulated player | Returns PlayerMock | | server.addPlayer(String) | Add player with specific name | | | PlayerMock | Simulated Player | Extends CraftPlayer-compatible mock | | player.assertSaid(String) | Assert chat message received | Exact string match | | player.assertNoMoreSaid() | Assert no more messages | | | server.getScheduler().performTicks(long) | Advance scheduler by N ticks | Triggers runTaskLater/runTaskTimer | | server.getScheduler().performOneTick() | Advance by 1 tick | | | MockBukkit.createMockPlugin() | Create a no-op plugin | For registering listeners under test |

Code Pattern

package com.yourorg.myplugin;

import be.seeseemelk.mockbukkit.MockBukkit;
import be.seeseemelk.mockbukkit.ServerMock;
import be.seeseemelk.mockbukkit.entity.PlayerMock;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.*;

class MyPluginTest {

    private ServerMock server;
    private MyPlugin plugin;

    @BeforeEach
    void setUp() {
        server = MockBukkit.mock();
        plugin = MockBukkit.load(MyPlugin.class);
    }

    @AfterEach
    void tearDown() {
        MockBukkit.unmock();
    }

    @Test
    void playerReceivesWelcomeMessage() {
        PlayerMock player = server.addPlayer();
        // Simulate the PlayerJoinEvent being triggered
        player.simulateLogin();

        player.assertSaid("Welcome, " + player.getName() + "!");
        player.assertNoMoreSaid();
    }

    @Test
    void scheduledTaskRunsAfterDelay() {
        PlayerMock player = server.addPlayer();
        plugin.scheduleReminder(player);

        // Fast-forward 5 seconds (100 ticks)
        server.getScheduler().performTicks(100L);

        player.assertSaid("Don't forget to vote!");
    }
}

Common Pitfalls

• Not calling MockBukkit.unmock() in @AfterEach: The mock server holds static state. Forgetting unmock() causes subsequent test classes to fail with "already mocked" errors.

• Using Bukkit.getServer() in non-mock code paths: Code that calls Bukkit.getServer() statically will return the ServerMock during tests, which is correct — but only after MockBukkit.mock() has been called.

• Testing async tasks with performTicks(): runTaskAsynchronously tasks are NOT executed by performTicks() — only synchronous main-thread tasks are. Refactor async code so the IO callback switches back to the main thread (testable part) and the IO layer is a separate mock.

• MockBukkit.load() triggers onEnable(): Your plugin's onEnable() runs during load(). If onEnable() depends on external services (e.g., Vault, a database), mock those before calling load().

• World not available by default: server.addSimpleWorld("world") creates a world. Calling Bukkit.getWorld("world") returns null unless added first.

Version Notes

• MockBukkit v4 (artifact id mockbukkit-v4) targets Paper 1.21. Earlier versions (mockbukkit-v1.x) target legacy Bukkit/Spigot and are not compatible.
• MockBukkit 4.x requires JUnit 5 (junit-jupiter). JUnit 4 annotations (@Before, @After) do not work.

Related Skills

• mockbukkit-patterns.md — Advanced patterns: config mocking, world mocking, event calling, command dispatch
• ../scheduling/scheduler-tasks.md — performTicks() maps to runTaskTimer tick counts
• ../events/custom-events.md — Calling and testing custom events