К основному содержанию
скилл CX Codex

minecraft-testing — скилл для Claude Code: что делает и как установить

Скилл minecraft-testing пишет и запускает автотесты для модов и плагинов Minecraft на JUnit, MockBukkit, NeoForge GameTests и Fabric GameTests.

MIT 386 установок ★ 211 обновлён 2026-10-30

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add Jahrome907/minecraft-agent-skills --skill minecraft-testing -a claude-code
Открыть на GitHub

Что делает minecraft-testing

Скилл берёт на себя выбор подхода к тестированию: чистые юнит-тесты на JUnit Jupiter для логики и NBT-сериализации, MockBukkit для событий, команд и инвентаря Bukkit/Paper-плагинов, GameTests у NeoForge и Fabric для проверки блоков, сущностей и мира прямо в игровом окружении. Внутри — готовые примеры кода для каждого случая: настройка build.gradle.kts, паттерны setUp/tearDown для MockBukkit, тесты на события (PlayerJoinEvent, BlockBreakEvent), команды плагина, инвентарь и планировщик.

Есть встроенный валидатор ./scripts/validate-test-layout.sh --root <project>: он проверяет статические зависимости, метаданные и структуру тестового layout перед тем, как копировать его в реальный проект, но не компилирует проект и не доказывает, что Game Test реально запустится. Для 26.x проектов скилл требует Java 25, для legacy 1.21.x — Java 21, а для Forge 1.20.1 — Java 17; версии и API разных линий смешивать нельзя. Скилл не занимается реализацией самой игровой механики и не публикует релизы — для этого в наборе есть отдельные скиллы minecraft-modding, minecraft-plugin-dev и minecraft-ci-release.

Какие задачи решает

  • написать юнит-тесты для NBT-сериализации и игровой логики без запуска Minecraft
  • проверить обработку событий Bukkit/Paper-плагина через MockBukkit
  • протестировать команды и права доступа плагина
  • покрыть тестами взаимодействие блоков и сущностей через NeoForge или Fabric GameTests
  • проверить layout тестов перед переносом в проект

Примеры запросов агенту

  • Напиши юнит-тест для CooldownManager на JUnit Jupiter
  • Настрой MockBukkit-тест для события PlayerJoinEvent в моём Paper-плагине
  • Проверь layout тестов через validate-test-layout.sh перед тем, как копировать его в проект

Как установить minecraft-testing

1Через Skills CLI (Vercel)

npx skills add Jahrome907/minecraft-agent-skills --skill minecraft-testing -a claude-code

2Вручную: положить файлы

~/.claude/skills/minecraft-testing/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/minecraft-testing/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о minecraft-testing

Как установить minecraft-testing в Claude Code?

Выполните npx skills add Jahrome907/minecraft-agent-skills --skill minecraft-testing -a claude-code, после чего скилл появится в ~/.claude/skills/minecraft-testing/SKILL.md.

Что делает minecraft-testing?

Скилл помогает проектировать и писать автотесты для модов и плагинов Minecraft: юнит-тесты на JUnit, мок-тесты Bukkit/Paper через MockBukkit и игровые тесты через NeoForge или Fabric GameTests.

Можно ли смешивать тесты для 26.x и легаси 1.21.x в одном проекте?

Нет: для 26.x нужна Java 25, для 1.21.x — Java 21, а для Forge 1.20.1 — Java 17, и версии API между линиями смешивать не стоит.

Исходный текст

SKILL.md · MIT
---
name: minecraft-testing
description: "Design and implement automated tests for current Minecraft 26.x or legacy 1.21.x mods and plugins using JUnit, MockBukkit, NeoForge Game Tests, or Fabric Game Tests. Use for test code and test execution, not release publishing or gameplay implementation."
---

# Minecraft Testing Skill

## Testing Strategies Overview

| Approach | Best For | Requires Game? |
|----------|---------|----------------|
| **JUnit Jupiter** (pure unit tests) | Logic, data structures, NBT serialization | No |
| **MockBukkit** | Bukkit/Paper plugin events, commands, inventory | No (mocked server) |
| **NeoForge GameTests** | In-game block/entity/world interaction | Yes (test environment) |
| **Fabric GameTests** | In-game block/entity/world interaction | Yes (test environment) |
| **Integration server** | Full plugin/mod lifecycle | Yes (dedicated test server) |

Use Java 25 for current 26.x projects. Keep legacy 1.21.x examples on Java 21
and Forge 1.20.1 on Java 17. Do not combine source layouts or APIs across versions.

### Routing Boundaries
- `Use when`: the task is designing or implementing automated tests (unit, mock, gametest, CI test jobs) for Minecraft projects.
- `Do not use when`: the task is implementing gameplay features rather than testing them (`minecraft-modding`, `minecraft-plugin-dev`, `minecraft-datapack`).
- `Do not use when`: the task is release automation or publishing pipelines (`minecraft-ci-release`).

## Bundled References And Helpers

- Layout guide: `references/test-layouts.md`
- Fixture/layout validator: `./scripts/validate-test-layout.sh --root <project>`

Use the validator before copying a test layout into a real project. It checks
visible static dependencies, metadata, and literal structure references. It does
not compile the project or prove a Game Test can run.

---

## Unit Testing (JUnit Jupiter — No Minecraft)

### JUnit Platform task
```kotlin
tasks.test {
    useJUnitPlatform()
    testLogging {
        events("passed", "skipped", "failed")
    }
}
```

For Fabric code that needs loader setup, use Fabric Loader JUnit rather than
assuming ordinary JUnit initialized Minecraft:

```groovy
dependencies {
    testImplementation "net.fabricmc:fabric-loader-junit:${project.loader_version}"
}

test {
    useJUnitPlatform()
}
```

When a unit test reaches registry-dependent Minecraft classes, initialize only
the required bootstrap in test setup. The current Fabric guide uses
`SharedConstants.tryDetectVersion()` and `Bootstrap.bootStrap()` for that case.

### Example pure unit test
```java
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class CooldownManagerTest {

    @Test
    void cooldown_tracksPlayersIndependently() {
        var manager = new CooldownManager(500L); // 500ms cooldown
        manager.startCooldown("steve");
        assertTrue(manager.isOnCooldown("steve"));
        assertFalse(manager.isOnCooldown("notExisting"));
    }

    @Test
    void cooldown_throwsIllegalArgument_onNegativeDuration() {
        assertThrows(IllegalArgumentException.class,
            () -> new CooldownManager(-1L));
    }
}
```

---

## MockBukkit (Paper/Bukkit Plugin Tests)

The paired dependencies below are a retained 26.2 example. For 26.3, verify
a published MockBukkit artifact for that exact Paper line before changing either
dependency; a 26.2 mock does not establish 26.3 server behavior.

### `build.gradle.kts`
```kotlin
repositories {
    maven("https://repo.papermc.io/repository/maven-public/")
    mavenCentral()
}

dependencies {
    compileOnly("io.papermc.paper:paper-api:26.2.build.+")
    testImplementation("org.junit.jupiter:junit-jupiter:6.1.3")
    testImplementation("org.mockbukkit.mockbukkit:mockbukkit-v26.2:4.116.1")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.test {
    useJUnitPlatform()
}
```

### Setup / teardown pattern
```java
import org.mockbukkit.mockbukkit.MockBukkit;
import org.mockbukkit.mockbukkit.ServerMock;
import org.mockbukkit.mockbukkit.entity.PlayerMock;
import org.junit.jupiter.api.*;

class MyPluginTest {

    private ServerMock server;
    private MyPlugin plugin;

    @BeforeEach
    void setUp() {
        // Start mock Bukkit server and load your plugin
        server = MockBukkit.mock();
        plugin = MockBukkit.load(MyPlugin.class);
    }

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

### Testing events
```java
@Test
void playerJoin_getsWelcomeMessage() {
    PlayerMock player = server.addPlayer("Steve"); // fires PlayerJoinEvent

    // Assert the message sent by the plugin's join listener.
    player.assertSaid("Welcome, Steve!");
}

@Test
void onBlockBreak_cancelledForNonOp() {
    PlayerMock player = server.addPlayer();
    player.setOp(false);

    Block block = player.getWorld().getBlockAt(0, 64, 0);
    block.setType(Material.STONE);
    BlockBreakEvent event = new BlockBreakEvent(block, player);
    server.getPluginManager().callEvent(event);

    assertTrue(event.isCancelled(), "Non-op should not be able to break blocks");
}
```

### Testing commands
```java
@Test
void mypluginInfo_returnsVersion() {
    PlayerMock player = server.addPlayer("Admin");
    player.setOp(true);

    boolean result = server.dispatchCommand(player, "myplugin info");

    assertTrue(result);
    player.assertSaid("Version: " + plugin.getDescription().getVersion());
}

@Test
void mypluginReload_requiresAdminPermission() {
    PlayerMock player = server.addPlayer("NonOp");
    player.setOp(false);

    server.dispatchCommand(player, "myplugin reload");

    player.assertSaid("No permission.");
}
```

### Testing inventory / items
```java
@Test
void giveKitCommand_givesPlayerItems() {
    PlayerMock player = server.addPlayer();
    
    server.dispatchCommand(player, "kit starter");
    
    // Check inventory
    assertTrue(player.getInventory().contains(Material.STONE_SWORD));
    assertTrue(player.getInventory().contains(Material.BREAD, 16));
}
```

### Testing scheduler tasks
```java
@Test
void repeatingTask_firesAfterDelay() {
    PlayerMock player = server.addPlayer();
    
    // Execute 40 ticks worth of scheduled tasks
    server.getScheduler().performTicks(40L);
    
    // Assert expected side effect happened
    assertEquals(2, plugin.getTaskCount());
}
```

### Testing Folia-safe scheduler abstractions

MockBukkit does not emulate Folia's region-threaded runtime. The safe pattern is to
wrap scheduling behind your own interface and unit test the abstraction boundary.

```java
interface SchedulerFacade {
    void runPlayerTask(Player player, Runnable task);
    void runAsync(Runnable task);
}

@Test
void playerTask_delegatesThroughFacade() {
    List<String> calls = new ArrayList<>();
    SchedulerFacade facade = new SchedulerFacade() {
        @Override
        public void runPlayerTask(Player player, Runnable task) {
            calls.add("player");
            task.run();
        }

        @Override
        public void runAsync(Runnable task) {
            calls.add("async");
            task.run();
        }
    };

    facade.runPlayerTask(server.addPlayer(), () -> calls.add("ran"));
    assertEquals(List.of("player", "ran"), calls);
}
```

### Testing PDC
```java
import java.util.ArrayList;
import org.bukkit.damage.DamageSource;
import org.bukkit.damage.DamageType;
import org.bukkit.entity.LivingEntity;

@Test
void pdcKillCount_incrementsOnKill() {
    PlayerMock player = server.addPlayer();
    NamespacedKey key = new NamespacedKey(plugin, "kills");

    // EntityDeathEvent requires a living victim and an explicit damage source.
    LivingEntity victim = (LivingEntity) server.addMockEntity(EntityType.ZOMBIE);
    DamageSource damageSource = DamageSource.builder(DamageType.GENERIC)
        .withCausingEntity(player)
        .withDirectEntity(player)
        .build();
    EntityDeathEvent deathEvent = new EntityDeathEvent(
        victim, damageSource, new ArrayList<>(), 0
    );
    server.getPluginManager().callEvent(deathEvent);

    int kills = player.getPersistentDataContainer()
        .getOrDefault(key, PersistentDataType.INTEGER, 0);
    assertEquals(1, kills);
}
```

This dispatches a synthetic death event. For player attribution, the listener
under test should read `event.getDamageSource().getCausingEntity()`; test actual
combat attribution separately on a real server.

### Testing item or chunk PDC writes
```java
@Test
void itemPdc_roundTripsCustomId() {
    NamespacedKey key = new NamespacedKey(plugin, "custom_id");
    ItemStack item = new ItemStack(Material.STICK);

    item.editMeta(meta -> meta.getPersistentDataContainer().set(
        key, PersistentDataType.STRING, "wand"
    ));

    String value = item.getItemMeta().getPersistentDataContainer()
        .get(key, PersistentDataType.STRING);
    assertEquals("wand", value);
}
```

---

## Current NeoForge Game Tests (26.x)

NeoForge 1.21.5 and later uses data-driven test environments and test instances,
not the old `@GameTestHolder` method-registration API. Store resources under
`data/<namespace>/test_environment/` and `data/<namespace>/test_instance/`.
A `test_instance` selects its environment, structure, timing, and either a
registered function or a block-based test.

```json
{
  "environment": "minecraft:default",
  "structure": "examplemod:example_structure",
  "max_ticks": 200,
  "setup_ticks": 0,
  "required": true,
  "type": "minecraft:function",
  "function": "examplemod:example_function"
}
```

Register the `Consumer<GameTestHelper>` with a `DeferredRegister` for the
current `BuiltInRegistries.TEST_FUNCTION` registry, then attach that register to
the mod event bus. The function below makes the JSON reference above usable.
Use `RegisterGameTestsEvent` only when registering environments and test
instances in code instead of data files. Keep the referenced structure in
`data/<namespace>/structure/<path>.nbt` and mark success explicitly.

```java
import java.util.function.Consumer;
import net.minecraft.core.registries.BuiltInRegistries;
import net.minecraft.gametest.framework.GameTestHelper;
import net.minecraft.world.level.block.Blocks;
import net.neoforged.bus.api.IEventBus;
import net.neoforged.fml.common.Mod;
import net.neoforged.neoforge.registries.DeferredHolder;
import net.neoforged.neoforge.registries.DeferredRegister;

@Mod(ExampleGameTests.MOD_ID)
public final class ExampleGameTests {
    public static final String MOD_ID = "examplemod";
    private static final DeferredRegister<Consumer<GameTestHelper>> TEST_FUNCTIONS =
        DeferredRegister.create(BuiltInRegistries.TEST_FUNCTION, MOD_ID);
    public static final DeferredHolder<Consumer<GameTestHelper>, Consumer<GameTestHelper>>
        EXAMPLE_FUNCTION = TEST_FUNCTIONS.register(
            "example_function", () -> ExampleGameTests::exampleTest
        );

    public ExampleGameTests(IEventBus modBus) {
        TEST_FUNCTIONS.register(modBus);
    }

    public static void exampleTest(GameTestHelper helper) {
        helper.assertBlockPresent(Blocks.AIR, 0, 0, 0);
        helper.succeed();
    }
}
```

Run `./gradlew runGameTestServer`; the server exits with the count of required
failed tests. This command is for a real project, not this skills repository.

---

## Current Fabric Game Tests (26.x)

Use Fabric Loom's dedicated Game Test source set. Configure it in the existing
`fabricApi` block and keep its metadata and code under `src/gametest`, separate
from ordinary unit tests.

```groovy
fabricApi {
    configureTests {
        createSourceSet = true
        modId = "example-mod-test-${project.name}"
        enableGameTests = true
        enableClientGameTests = true
        eula = true
    }
}
```

Place `fabric.mod.json` in `src/gametest/resources/` and register server tests
under `fabric-gametest`; use `fabric-client-gametest` for client tests. Implement
server methods with Fabric's `net.fabricmc.fabric.api.gametest.v1.GameTest` and,
when setup is needed before a method runs, `CustomTestMethodInvoker`.

```java
package com.example.mymod;

import java.lang.reflect.Method;
import net.fabricmc.fabric.api.gametest.v1.CustomTestMethodInvoker;
import net.fabricmc.fabric.api.gametest.v1.GameTest;
import net.minecraft.gametest.framework.GameTestHelper;
import net.minecraft.world.level.block.Blocks;

public final class ExampleGameTest implements CustomTestMethodInvoker {
    @GameTest
    public void testBlock(GameTestHelper context) {
        context.assertBlockPresent(Blocks.AIR, 0, 0, 0);
        context.succeed();
    }

    @Override
    public void invokeTestMethod(GameTestHelper context, Method method)
            throws ReflectiveOperationException {
        method.invoke(this, context);
    }
}
```

### `src/gametest/resources/fabric.mod.json`
```json
{
  "entrypoints": {
    "fabric-gametest": [
      "com.example.mymod.ExampleGameTest"
    ]
  }
}
```

Keep the `fabric-gametest` entrypoint in sync with the concrete Game Test class.
Fabric's server Game Tests run with `build`; use `runClientGameTest` for client
tests. Follow the current Fabric documentation for project-specific Loom options
and headless client CI.

---

## Legacy NeoForge Game Tests (1.21.3 only)

Keep annotation-based tests isolated to Minecraft 1.21.3. The class can
be registered by either `@GameTestHolder(MOD_ID)` or a
`RegisterGameTestsEvent` listener. Do not register a `@GameTestHolder` class
again with `modEventBus.register(MyGameTests.class)`.

```java
import net.minecraft.gametest.framework.GameTest;
import net.minecraft.gametest.framework.GameTestHelper;
import net.neoforged.neoforge.gametest.GameTestHolder;
import net.neoforged.neoforge.gametest.PrefixGameTestTemplate;

@GameTestHolder("examplemod")
@PrefixGameTestTemplate(false)
public final class ExampleGameTests {
    @GameTest(template = "example_structure")
    public static void smoke(GameTestHelper helper) {
        helper.succeed();
    }
}
```

For `RegisterGameTestsEvent`, register the class on the mod event bus and set
`templateNamespace = MOD_ID` on each `@GameTest`. Legacy templates are `.nbt`
files under `data/<namespace>/structure/`; `@PrefixGameTestTemplate(false)`
controls whether the class name is added to the template path. When `template`
is omitted, the path uses the lowercase method name and, unless that prefix is
disabled, the lowercase simple class name followed by a dot. `template` is the
path name only; configure its namespace through `templateNamespace` or
`@GameTestHolder`.

---

## CI

Keep fast unit/mock tests separate from a loader's Game Test task, and select
the Java version for each Minecraft version: 25 for 26.x, 21 for 1.21.x, and 17 for Forge 1.20.1.
Upload test reports when a runtime-facing job fails. Do not assume a task name
from another loader: Fabric server Game Tests run with `build`, while NeoForge
uses `runGameTestServer`. MockBukkit does not prove Folia thread safety or real
server bootstrap.

---

## References

- MockBukkit GitHub: https://github.com/MockBukkit/MockBukkit
- MockBukkit docs: https://docs.mockbukkit.org/
- Fabric automated testing: https://docs.fabricmc.net/develop/automatic-testing
- NeoForge 26.x Game Tests: https://docs.neoforged.net/docs/misc/gametest/
- NeoForge 1.21.3 Game Tests: https://docs.neoforged.net/docs/1.21.3/misc/gametest/
- JUnit Jupiter user guide: https://junit.org/junit5/docs/current/user-guide/

© Jahrome907 · MIT · Jahrome907/minecraft-agent-skills

Похожие скиллы

Все скиллы по теме «Тесты и QA» →
minecraft-bukkit-pro rmyndharis Скилл minecraft-bukkit-pro для Claude Code помогает разрабатывать плагины Minecraft через Bukkit, Spigot и Paper. Включается для архитектуры, команд, событий и оптимизации сервера. CX Codex +1 131установок minecraft-plugin-development официальный github Скилл minecraft-plugin-development помогает создавать и отлаживать серверные плагины для Paper, Spigot и Bukkit. Настраивает команды, слушатели событий, конфиги и игровые механики. CX Codex +1 485установок minecraft-mcp MakkCH Позволяющий ИИ-агенту управлять персонажем в Minecraft. Агент выполняет JavaScript-сценарии через JsMacros, делает снимки экрана и общается в игровом чате. CX Codex +1 ★ 26звёзд репо create-simulated-aeronautics-mod reason-machines Скилл create-simulated-aeronautics-mod для Claude Code, Codex, Cursor, Copilot, Gemini CLI и OpenCode с экспертизой в Create Simulated — моде NeoForge, добавляющем в Minecraft физичные конструкции (самолёты, дирижабли, машины). CX Codex +1 398установок game-development Seth Hobson Плагин game-development помогает с разработкой игр на Unity с C# и серверных плагинов Minecraft через Bukkit/Spigot API. Укажите агенту, для какой из этих сред нужна работа. CX Codex ★ 42 780звёзд репо code-testing-extensions dotnet Скилл code-testing-extensions для Claude Code — каталог путей к файлам инструкций для пайплайна тестирования кода; агент читает нужный файл напрямую. CX Codex +1 4 600установок

Из того же набора13

Весь набор →
minecraft-modding Скилл minecraft-modding пишет и правит код модов Minecraft под NeoForge, Fabric 26.x, 1.21.x и Forge 1.20.1. Определяет платформу по gradle.properties и build.gradle перед тем, как трогать код. CX Codex +1 966установок minecraft-resource-pack Скилл minecraft-resource-pack помогает собирать и отлаживать ресурс-паки Minecraft версий 1.21.x и 26.x. Генерирует модели блоков, звуковые карты, шрифты и конфиги pack.mcmeta без изменения серверного кода игры. CX Codex +1 385установок minecraft-datapack Скилл minecraft-datapack создаёт и отлаживает датапаки для Minecraft 1.21.x и 26.x. Помогает собрать структуру папок, функции, таблицы лута и настроить pack.mcmeta без модов. CX Codex +1 300установок minecraft-server-admin Скилл minecraft-server-admin для Claude Code ведёт Java-серверы Minecraft: Paper, Purpur, Folia, Velocity, Fabric и NeoForge. Разбирает падение TPS, отказ прокси и ошибки запуска версии. CX Codex +1 279установок minecraft-world-generation Скилл minecraft-world-generation для Claude Code помогает создавать и отлаживать генерацию мира Minecraft в датапаках и модах NeoForge или Fabric. Он подключается к задачам с биомами, измерениями, структурами и регистрацией worldgen-данных. CX Codex +1 269установок minecraft-plugin-dev Скилл minecraft-plugin-dev помогает создавать, менять и отлаживать серверные плагины для Paper и Bukkit-производных серверов. Пригодится при работе с JavaPlugin, событиями и командами. CX Codex +1 267установок minecraft-multiloader Скилл minecraft-multiloader настраивает моды Minecraft на базе Architectury для версий 26.x и 1.21.x с общей кодовой базой под NeoForge и Fabric. Включается при одновременной поддержке обоих загрузчиков. CX Codex +1 247установок minecraft-commands-scripting Скилл minecraft-commands-scripting генерирует и отлаживает команды Minecraft Java 26.x и 1.21.x, цепочки execute, скорборды и RCON-скрипты. Работает со строками команд без сборки структуры датапаков. CX Codex +1 241установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой