JBukkit is a library created for unit testing Bukkit related projects.

It does so by providing many implementations of Bukkit classes with the help of JUnit5 and Mockito.

Table of contents
How to import
How to choose module version
How to use

How to import

JBukkit can be imported using one of the three most common methods:

• Gradle (preferred):

  repositories {
      maven { url = 'https://repo.fulminazzo.it/releases' }
  }
  
  dependencies {
      // Imports the latest module
      implementation 'it.fulminazzo:jbukkit:latest'
  }

• Maven (alternative):

  <repository>
      <id>fulminazzo</id>
      <url>https://repo.fulminazzo.it/releases</url>
  </repository>

  <!-- Imports the latest module -->
  <dependency>
      <groupId>it.fulminazzo</groupId>
      <artifact>jbukkit</artifact>
      <version>LATEST</version>
  </dependency>

• Manual (discouraged): download the JAR file from the latest release and import it using your IDE.

Version choice

JBukkit provides one version for every Minecraft version from 1.8 to the latest. To choose the correct one, the second leading number should be used as reference for the modules.

So, for example, when importing for Minecraft 1.13:

• Gradle (preferred):

  dependencies {
      implementation 'it.fulminazzo.jbukkit:13:latest'
  }

• Maven (alternative):

  <dependency>
      <groupId>it.fulminazzo.jbukkit</groupId>
      <artifact>13</artifact>
      <version>LATEST</version>
  </dependency>

NOTE: every module uses as reference the latest patch of its version. This means that module 13 is compatible with Minecraft 1.13.2, but might not support Minecraft 1.13 and 1.13.2.

How to use

After importing the project with the appropriate version, it is possible to create a JUnit test.

The main class of reference for JBukkit is BukkitUtils which provides various methods:

• setUp (mandatory for proper functioning): it verifies the Minecraft version in use. This method will also use the annotations Before1_ and After1_ to check if the current version is, respectively, before or after the specified versions. If it is not, the annotated tests will be skipped;

• setupServer: initializes the Bukkit#getServer object with various parameters (loggers, recipes, support for inventories creation, players list and more). In Minecraft 1.20+ it initializes the registries, mandatory for certain classes;

• setupEnchantments: initializes all the enchantments found in the Bukkit Enchantment class. The initialization method and the parameters will vary from version to version;

• various Player and OfflinePlayer methods to add, remove or get players.

  NOTE: at the time of writing, adding a player will not trigger PlayerJoinEvent.

To use BukkitUtils it is possible to extend it from the testing class and calling the super method setUp:

import it.fulminazzo.jbukkit.BukkitUtils;

class PluginTest extends BukkitUtils {
    
    @BeforeEach
    void setUp() {
        super.setUp();
    }
    
}

JBukkit offers the possibility to create many Bukkit API classes and interfaces, using mock versions of them, in order to replicate the expected behaviour in a real server environment.

To check if such a class exists for the target type, simply add "Mock" in front of the type name. For example, for Inventory the MockInventory class is found.

NOTE: many of the mocks are version dependent, therefore they might change for each module.