Testing Minecraft Plugins and Minigames - A Developer's Guide

<dependencies>
    <!-- Paper API -->
    <dependency>
        <groupId>io.papermc.paper</groupId>
        <artifactId>paper-api</artifactId>
        <version>1.21-R0.1-SNAPSHOT</version>
        <scope>provided</scope>
    </dependency>

    <!-- MockBukkit for testing -->
    <dependency>
        <groupId>com.github.seeseemelk</groupId>
        <artifactId>MockBukkit-v1.21</artifactId>
        <version>4.0.0</version>
        <scope>test</scope>
    </dependency>

    <!-- JUnit 5 -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.10.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

dependencies {
    compileOnly 'io.papermc.paper:paper-api:1.21-R0.1-SNAPSHOT'

    testImplementation 'com.github.seeseemelk:MockBukkit-v1.21:4.0.0'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.2'
}

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.*;

public class MyPluginTest {

    private ServerMock server;
    private MyPlugin plugin;

    @BeforeEach
    public void setUp() {
        // Create mock server
        server = MockBukkit.mock();

        // Load your plugin
        plugin = MockBukkit.load(MyPlugin.class);
    }

    @AfterEach
    public void tearDown() {
        // Clean up after each test
        MockBukkit.unmock();
    }

    @Test
    public void testPluginLoads() {
        assertNotNull(plugin);
        assertTrue(plugin.isEnabled());
    }
}

@Test
public void testFlyCommand() {
    // Create a player
    PlayerMock player = server.addPlayer("TestPlayer");

    // Execute command
    boolean success = server.dispatchCommand(player, "fly");

    // Verify
    assertTrue(success, "Command should execute successfully");
    assertTrue(player.getAllowFlight(), "Player should have flight enabled");

    // Check player received message
    player.assertSaid("Flight enabled!");
}

@Test
public void testFlyCommandRequiresPermission() {
    PlayerMock player = server.addPlayer("TestPlayer");

    // Player has no permission
    assertFalse(player.hasPermission("myplugin.fly"));

    // Command should fail
    server.dispatchCommand(player, "fly");

    // Player shouldn't have flight
    assertFalse(player.getAllowFlight());

    // Check error message
    player.assertSaid("You don't have permission!");
}

@Test
public void testPlayerJoinMessage() {
    PlayerMock player = server.addPlayer("NewPlayer");

    // Trigger join event
    PlayerJoinEvent event = new PlayerJoinEvent(player, "NewPlayer joined");
    server.getPluginManager().callEvent(event);

    // Verify plugin handled event
    assertEquals("&eWelcome, NewPlayer!", event.getJoinMessage());
}

@Test
public void testDamageReduction() {
    PlayerMock player = server.addPlayer("TestPlayer");

    // Give player armor
    ItemStack helmet = new ItemStack(Material.DIAMOND_HELMET);
    player.getInventory().setHelmet(helmet);

    // Create damage event
    EntityDamageEvent event = new EntityDamageEvent(
        player,
        EntityDamageEvent.DamageCause.ENTITY_ATTACK,
        10.0
    );

    server.getPluginManager().callEvent(event);

    // Plugin should reduce damage
    assertTrue(event.getDamage() < 10.0, "Damage should be reduced");
}

@Test
public void testConfigDefaults() {
    FileConfiguration config = plugin.getConfig();

    assertEquals(100, config.getInt("max-health"));
    assertEquals(true, config.getBoolean("enable-pvp"));
    assertEquals("Welcome!", config.getString("join-message"));
}

@Test
public void testConfigReload() {
    // Modify config
    plugin.getConfig().set("max-health", 200);
    plugin.saveConfig();

    // Reload plugin
    plugin.reloadConfig();

    // Verify change persisted
    assertEquals(200, plugin.getConfig().getInt("max-health"));
}

@Test
public void testAsyncTask() throws InterruptedException {
    PlayerMock player = server.addPlayer("TestPlayer");
    AtomicBoolean taskRan = new AtomicBoolean(false);

    // Schedule async task
    Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
        // Simulate database query
        try {
            Thread.sleep(100);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
        taskRan.set(true);
    });

    // Wait for async task
    Thread.sleep(200);

    assertTrue(taskRan.get(), "Async task should have run");
}

@Test
public void testShopGUI() {
    PlayerMock player = server.addPlayer("TestPlayer");

    // Open shop GUI
    plugin.openShopGUI(player);

    // Get opened inventory
    Inventory inv = player.getOpenInventory().getTopInventory();

    assertEquals(27, inv.getSize(), "Shop should be 3 rows");
    assertEquals("&6Shop", inv.getTitle());

    // Check items
    ItemStack sword = inv.getItem(0);
    assertNotNull(sword);
    assertEquals(Material.DIAMOND_SWORD, sword.getType());
}

@Test
public void testInventoryClick() {
    PlayerMock player = server.addPlayer("TestPlayer");
    plugin.openShopGUI(player);

    Inventory inv = player.getOpenInventory().getTopInventory();

    // Simulate click
    InventoryClickEvent event = new InventoryClickEvent(
        player.getOpenInventory(),
        InventoryType.SlotType.CONTAINER,
        0, // slot
        ClickType.LEFT,
        InventoryAction.PICKUP_ALL
    );

    server.getPluginManager().callEvent(event);

    // Verify purchase logic ran
    assertTrue(event.isCancelled(), "Event should be cancelled");
    // Verify player received item, money deducted, etc.
}

<dependency>
    <groupId>io.github.alchemist-itroad</groupId>
    <artifactId>watchwolf</artifactId>
    <version>1.2.0</version>
    <scope>test</scope>
</dependency>

import io.github.alchemist.watchwolf.WatchWolf;
import io.github.alchemist.watchwolf.api.clients.ClientDescriptor;
import io.github.alchemist.watchwolf.api.servers.ServerDescriptor;
import org.junit.jupiter.api.Test;

public class MinigameIntegrationTest {

    @Test
    public void testMinigameFlow() throws Exception {
        try (WatchWolf watchWolf = new WatchWolf()) {
            // Start server
            ServerDescriptor server = watchWolf.startServer("1.21", "paper");
            server.installPlugin("MyPlugin.jar");
            server.waitForStartup();

            // Connect clients
            ClientDescriptor player1 = watchWolf.startClient("Player1");
            ClientDescriptor player2 = watchWolf.startClient("Player2");

            player1.connect(server);
            player2.connect(server);

            // Execute minigame commands
            player1.executeCommand("/minigame join");
            player2.executeCommand("/minigame join");

            // Wait for minigame to start
            Thread.sleep(5000);

            // Verify both players in game
            assertTrue(server.isPlayerOnline("Player1"));
            assertTrue(server.isPlayerOnline("Player2"));

            // Test minigame logic...
        }
    }
}

@Test
public void testMinigameLifecycle() {
    // Setup
    Minigame game = new Minigame("TestArena");

    // Test initial state
    assertEquals(GameState.WAITING, game.getState());

    // Add players
    Player p1 = server.addPlayer("Player1");
    Player p2 = server.addPlayer("Player2");

    game.addPlayer(p1);
    game.addPlayer(p2);

    assertEquals(2, game.getPlayerCount());

    // Start game
    game.start();
    assertEquals(GameState.ACTIVE, game.getState());

    // Player leaves
    game.removePlayer(p1);
    assertEquals(1, game.getPlayerCount());

    // End game
    game.end();
    assertEquals(GameState.ENDED, game.getState());

    // Verify cleanup
    assertTrue(game.getPlayers().isEmpty());
}

@Test
public void testLastPlayerStanding() {
    Minigame game = new Minigame("PvPArena");

    Player p1 = server.addPlayer("Player1");
    Player p2 = server.addPlayer("Player2");
    Player p3 = server.addPlayer("Player3");

    game.addPlayer(p1);
    game.addPlayer(p2);
    game.addPlayer(p3);

    game.start();

    // Simulate players dying
    game.handlePlayerDeath(p2);
    game.handlePlayerDeath(p3);

    // Game should end, p1 should win
    assertEquals(GameState.ENDED, game.getState());
    assertEquals(p1, game.getWinner());
}

@Test
public void testTeamBalancing() {
    TeamMinigame game = new TeamMinigame("CaptureTheFlag");

    // Add 10 players
    for (int i = 1; i <= 10; i++) {
        Player p = server.addPlayer("Player" + i);
        game.addPlayer(p);
    }

    // Assign teams
    game.balanceTeams();

    // Each team should have 5 players
    assertEquals(5, game.getTeam("RED").size());
    assertEquals(5, game.getTeam("BLUE").size());

    // Players should not be on both teams
    for (Player p : game.getTeam("RED")) {
        assertFalse(game.getTeam("BLUE").contains(p));
    }
}

@Test
public void testScoring() {
    Minigame game = new Minigame("Spleef");
    Player p1 = server.addPlayer("Player1");

    game.addPlayer(p1);
    game.start();

    // Initial score
    assertEquals(0, game.getScore(p1));

    // Player scores points
    game.addScore(p1, 10);
    assertEquals(10, game.getScore(p1));

    // Multiple score additions
    game.addScore(p1, 5);
    game.addScore(p1, 3);
    assertEquals(18, game.getScore(p1));
}

@Test
public void testSpectatorMode() {
    Minigame game = new Minigame("BedWars");
    Player p1 = server.addPlayer("Player1");

    game.addPlayer(p1);
    game.start();

    // Player dies, becomes spectator
    game.handlePlayerDeath(p1);

    assertTrue(game.isSpectator(p1));
    assertEquals(GameMode.SPECTATOR, p1.getGameMode());

    // Spectator can't interact
    assertFalse(game.canBreakBlocks(p1));
    assertFalse(game.canDamageEntities(p1));

    // Spectator shouldn't count toward win conditions
    assertEquals(0, game.getActivePlayers().size());
}

@Test
public void testArenaRestoration() {
    Arena arena = new Arena("PvPArena");
    World world = server.addSimpleWorld("arena_world");

    // Set arena bounds
    Location corner1 = new Location(world, 0, 64, 0);
    Location corner2 = new Location(world, 10, 74, 10);
    arena.setRegion(corner1, corner2);

    // Save initial state
    arena.saveSnapshot();

    // Modify arena (simulate gameplay)
    world.getBlockAt(5, 65, 5).setType(Material.AIR);
    world.getBlockAt(3, 66, 3).setType(Material.TNT);

    // Restore arena
    arena.restoreSnapshot();

    // Verify restoration
    assertEquals(Material.GRASS_BLOCK, world.getBlockAt(5, 65, 5).getType());
    assertEquals(Material.AIR, world.getBlockAt(3, 66, 3).getType());
}

@Test
public void testPartySystem() {
    Player leader = server.addPlayer("Leader");
    Player member1 = server.addPlayer("Member1");
    Player member2 = server.addPlayer("Member2");

    // Create party
    server.dispatchCommand(leader, "party create");

    // Invite members
    server.dispatchCommand(leader, "party invite Member1");
    server.dispatchCommand(leader, "party invite Member2");

    // Members accept
    server.dispatchCommand(member1, "party accept");
    server.dispatchCommand(member2, "party accept");

    // Verify party
    Party party = plugin.getPartyManager().getParty(leader);
    assertNotNull(party);
    assertEquals(3, party.getMembers().size());
    assertTrue(party.isLeader(leader));
    assertTrue(party.isMember(member1));
    assertTrue(party.isMember(member2));
}

@Test
public void testPerformanceUnderLoad() {
    long startTime = System.currentTimeMillis();

    // Add 100 players
    List<PlayerMock> players = new ArrayList<>();
    for (int i = 0; i < 100; i++) {
        players.add(server.addPlayer("Player" + i));
    }

    long endTime = System.currentTimeMillis();
    long duration = endTime - startTime;

    // Should complete in reasonable time
    assertTrue(duration < 5000, "Adding 100 players took " + duration + "ms");

    // Test plugin operations with 100 players
    startTime = System.currentTimeMillis();

    for (PlayerMock player : players) {
        plugin.processPlayer(player); // Your plugin logic
    }

    endTime = System.currentTimeMillis();
    duration = endTime - startTime;

    // Processing 100 players should be fast
    assertTrue(duration < 1000, "Processing 100 players took " + duration + "ms");
}

name: Plugin Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Set up JDK 21
        uses: actions/setup-java@v3
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Cache Maven packages
        uses: actions/cache@v3
        with:
          path: ~/.m2
          key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}

      - name: Run tests
        run: mvn test

      - name: Generate test report
        if: always()
        uses: dorny/test-reporter@v1
        with:
          name: Test Results
          path: target/surefire-reports/*.xml
          reporter: java-junit

Goal: Verify minigame starts when enough players join

Setup:
- Set minigame to require 8 players
- Configure 2-second countdown after threshold reached

Test:
1. Connect 7 bots - minigame should stay in lobby
2. Connect 8th bot - countdown should start
3. Wait 2 seconds - minigame should start
4. Verify all 8 players marked as "active"

Expected: Minigame starts exactly when requirements met

Goal: Ensure players joining during active game are handled correctly

Test:
1. Start minigame with 8 bots
2. After game starts, connect 9th bot
3. Verify 9th bot becomes spectator (or is rejected)
4. Verify 9th bot doesn't interfere with gameplay

Expected: Late joiners can't disrupt active game

Goal: Handle disconnects gracefully

Test:
1. Start minigame with 4 bots
2. Disconnect 1 bot mid-game
3. Verify game continues with 3 players
4. Verify disconnected player cleaned up properly

Expected: Game remains stable after disconnect

Goal: Test concurrent player interactions

Test:
1. Start minigame with 10 bots
2. All bots execute action simultaneously (break block, open chest, etc.)
3. Verify all actions processed correctly
4. Verify no race conditions or data corruption

Expected: Thread-safe handling of concurrent actions

Goal: Ensure minigame remains stable over time

Test:
1. Start minigame with 8 bots
2. Run for 30 minutes
3. Monitor memory usage, TPS, errors
4. Complete minigame cycle (start -> play -> end -> restart)

Expected: No memory leaks, stable performance

Minigame: Bed Wars (requires 8 players)

SoulFire Config:
- Bots: 8
- Join Delay: 2000-4000ms (stagger joins naturally)
- Plugins:
  - Auto Respawn (handle deaths)
  - Anti-AFK (move around)
  - Auto Jump (simulate player activity)

Test Procedure:
1. Start bots joining lobby
2. Monitor server logs for minigame start
3. Let minigame run for 5 minutes
4. Check for errors, crashes, or unexpected behavior
5. Verify minigame ends properly
6. Confirm cleanup (players returned to lobby, arena restored)

# Server TPS during minigame
/spark tps

# Check for errors
tail -f logs/latest.log | grep -i error

# Monitor plugin-specific metrics
/minigame stats

# Memory usage
/spark heapsummary

✅ All 8 bots joined successfully
✅ Minigame started in 3 seconds after 8th join
✅ No errors in 10-minute test
✅ TPS remained 19-20 throughout
✅ Minigame ended and reset properly

❌ Only 6/8 bots joined (check join logic)
❌ Minigame never started (check player detection)
❌ TPS dropped to 15 (performance issue)
❌ Errors in console (bug in game logic)
❌ Arena not restored (cleanup bug)

#!/bin/bash

echo "Starting minigame test..."

# Start test server
./start-test-server.sh &
sleep 30  # Wait for server startup

# Start bots (using your bot tool)
start_bots 8

# Wait for minigame to start (check logs)
timeout=60
elapsed=0
while ! grep -q "Minigame started" logs/latest.log; do
  sleep 1
  elapsed=$((elapsed + 1))
  if [ $elapsed -ge $timeout ]; then
    echo "FAIL: Minigame never started"
    exit 1
  fi
done

echo "✅ Minigame started after $elapsed seconds"

# Let game run for 5 minutes
sleep 300

# Check for errors
if grep -q "ERROR" logs/latest.log; then
  echo "❌ FAIL: Errors detected"
  grep "ERROR" logs/latest.log
  exit 1
fi

echo "✅ No errors detected"

# Stop bots
stop_bots

# Check cleanup
sleep 10
if ! grep -q "Arena restored" logs/latest.log; then
  echo "⚠️  WARNING: Arena may not have restored"
fi

echo "✅ Test complete"